Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

docs: state the release cadence in CONTRIBUTING and the docs site (#2850)

Hector Ventura10ce6be8cd89
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c54248dfe8..a3ebf2a487 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,14 +2,14 @@
Thank you for your interest in contributing! Floci is a community-driven project and all contributions are welcome.
-**Join us on [Slack](https://join.slack.com/t/floci/shared_invite/zt-3tjn02s3q-A00kEjJ1cZxsg_imTfy6Cw)** — it is the fastest way to reach maintainers. Ask about AWS behaviour, sanity-check an approach before you build it, or get unstuck on a PR.
+**Join us on [Slack](https://join.slack.com/t/floci/shared_invite/zt-3tjn02s3q-A00kEjJ1cZxsg_imTfy6Cw)**: it is the fastest way to reach maintainers. Ask about AWS behaviour, sanity-check an approach before you build it, or get unstuck on a PR.
## Ways to Contribute
-- **Bug reports** — open an issue with a minimal reproduction
-- **Feature requests** — open an issue describing the AWS behavior you need
-- **Pull requests** — bug fixes, new service implementations, or improvements
-- **Compatibility tests** — add cases to `./compatibility-tests/`
+- **Bug reports**: open an issue with a minimal reproduction
+- **Feature requests**: open an issue describing the AWS behavior you need
+- **Pull requests**: bug fixes, new service implementations, or improvements
+- **Compatibility tests**: add cases to `./compatibility-tests/`
## Getting Started
@@ -49,16 +49,16 @@ If you prefer to use your own Maven installation (3.9+), you can use `mvn` inste
## Branching Model
-Floci uses a **tag-driven release model**. Docker images are never published on PR merge — only when a maintainer pushes a version tag.
+Floci uses a **tag-driven release model**. Docker images are never published on PR merge, only when a maintainer pushes a version tag.
| Branch | Purpose | Docker published? |
|---|---|---|
-| `main` | Integration branch — all PRs merge here. Treated as unstable/nightly. | No (CI tests only) |
+| `main` | Integration branch: all PRs merge here. Treated as unstable/nightly. | No (CI tests only) |
| `X.Y.Z` tag | Signals a production release. Triggers the full Docker publish pipeline. | Yes (`x.y.z`, `latest`, `x.y.z-jvm`, `latest-jvm`) |
## Commit Message Format
-This project uses [Conventional Commits](https://www.conventionalcommits.org/) — semantic-release reads these to generate the changelog and version bumps automatically.
+This project uses [Conventional Commits](https://www.conventionalcommits.org/): semantic-release reads these to generate the changelog and version bumps automatically.
> **The PR title is validated automatically by CI** and must follow this format, since it becomes the squash-merge commit message that semantic-release reads.
@@ -68,9 +68,9 @@ This project uses [Conventional Commits](https://www.conventionalcommits.org/)
<type>[optional scope]: <description>
```
-- **type** — one of the values in the table below (lowercase)
-- **scope** — optional, in parentheses, identifies the service or area (e.g. `s3`, `dynamodb`, `core`)
-- **description** — short summary in the imperative mood, no trailing period
+- **type**: one of the values in the table below (lowercase)
+- **scope**: optional, in parentheses, identifies the service or area (e.g. `s3`, `dynamodb`, `core`)
+- **description**: short summary in the imperative mood, no trailing period
- Append `!` before the colon to signal a breaking change: `feat(api)!:`
| Type | When to use | Version bump |
@@ -80,13 +80,13 @@ This project uses [Conventional Commits](https://www.conventionalcommits.org/)
| `perf` | Performance improvement | patch |
| `revert` | Reverts a previous commit | patch |
| `docs` | Documentation only | none |
-| `style` | Formatting, whitespace — no logic change | none |
+| `style` | Formatting, whitespace, no logic change | none |
| `chore` | Build, CI, dependencies, housekeeping | none |
| `refactor` | Code restructure without behavior change | none |
| `test` | Adding or updating tests | none |
| `build` | Build system or tooling changes | none |
| `ci` | CI workflow changes | none |
-| `BREAKING CHANGE` | Footer or `!` suffix — incompatible change | major |
+| `BREAKING CHANGE` | Footer or `!` suffix, incompatible change | major |
### Valid examples ✅
@@ -120,7 +120,7 @@ wip: still working on this # "wip" is not a recognised type
Do not include `Co-Authored-By` trailers for AI tools in commit messages. Attribution should be limited to human contributors.
-CI enforces this: the **Commits omit AI attribution trailers** check fails a pull request whose commits carry a `Co-Authored-By` for an identity that is not a person — one whose GitHub address belongs to a bot account, or that uses a `noreply@` mailbox — along with the session and generator lines such tools add on their own. It never judges a co-author by name, so co-authoring a person is always fine; that trailer is how GitHub credits reviewers on a squash merge. `dependabot[bot]` is allowlisted. If the check fires, drop the offending lines with `git commit --amend` (or a rebase for several commits) and force-push.
+CI enforces this: the **Commits omit AI attribution trailers** check fails a pull request whose commits carry a `Co-Authored-By` for an identity that is not a person (one whose GitHub address belongs to a bot account, or that uses a `noreply@` mailbox), along with the session and generator lines such tools add on their own. It never judges a co-author by name, so co-authoring a person is always fine; that trailer is how GitHub credits reviewers on a squash merge. `dependabot[bot]` is allowlisted. If the check fires, drop the offending lines with `git commit --amend` (or a rebase for several commits) and force-push.
## Architecture
@@ -137,7 +137,7 @@ ln -s AGENTS.md COPILOT.md
## Adding a New AWS Service
1. Create a package under `src/main/java/.../services/<service>/`
-2. Add a Controller (follow the correct protocol — Query, JSON 1.1, REST JSON, or REST XML)
+2. Add a Controller (follow the correct protocol: Query, JSON 1.1, REST JSON, or REST XML)
3. Add a Service (`@ApplicationScoped`) and model POJOs
4. Add config entries in `EmulatorConfig.java` and `application.yml`
5. Register a `ServiceDescriptor` in `ResolvedServiceCatalog`
@@ -146,24 +146,24 @@ ln -s AGENTS.md COPILOT.md
`ServiceRegistry`, `ServiceEnabledFilter`, and `StorageFactory` now resolve service metadata from the descriptor catalog. Adding a service should not require new service-keyed switch statements in those consumers.
-Always implement the **real AWS wire protocol** — never invent custom endpoints. The AWS SDK must work against Floci without modification.
+Always implement the **real AWS wire protocol**. Never invent custom endpoints. The AWS SDK must work against Floci without modification.
## Adding a CloudFormation Resource Type
CloudFormation resource types live in **per-service provisioner classes**, not in
-`CloudFormationResourceProvisioner`. That class is a legacy monolith being dismantled — please do
+`CloudFormationResourceProvisioner`. That class is a legacy monolith being dismantled, so please do
not add cases to it. If the service you need already has a `*CfnProvisioner`, add your type there;
otherwise create one.
1. Create `services/cloudformation/provisioners/<Service>CfnProvisioner.java`, annotate it
- `@ApplicationScoped`, and inject **only** the service it wraps. Registration is automatic —
+ `@ApplicationScoped`, and inject **only** the service it wraps. Registration is automatic:
`CloudFormationResourceRegistry` discovers it via CDI. (Forgetting `@ApplicationScoped` compiles
and unit-tests green, but the type is never wired.)
2. Implement `resourceTypes()` returning every `AWS::*` type the class serves, and `provision(...)`.
When you serve more than one type, switch on `resource.getResourceType()`.
3. In `provision`, set **both**:
- - `resource.setPhysicalId(...)` — this is what `Ref` resolves to
- - `resource.getAttributes().put("Name", value)` for every `Fn::GetAtt` attribute — a *separate*
+ - `resource.setPhysicalId(...)`: this is what `Ref` resolves to
+ - `resource.getAttributes().put("Name", value)` for every `Fn::GetAtt` attribute, a *separate*
map. Forgetting it does not fail: `Fn::GetAtt` silently resolves to the literal string
`"LogicalId.Attr"`. Take the attribute names from the resource's registry schema under
`local/aws/cfn-resource-schemas/us-east-1/` (`readOnlyProperties`).
@@ -173,7 +173,7 @@ otherwise create one.
`AlreadyExists` or orphan the old resource.
5. Override `delete(...)` if the type has a backing delete. Deleting a resource that is already gone
should be tolerated.
-6. Add a focused unit test (mock only your service — see `SqsCfnProvisionerTest`) and an integration
+6. Add a focused unit test (mock only your service, see `SqsCfnProvisionerTest`) and an integration
test. Assert the **specific `Fn::GetAtt` attribute keys**, not just `CREATE_COMPLETE`: an
unmapped type is stubbed out as a successful no-op, so a status-only assertion passes even when
nothing was provisioned.
@@ -186,15 +186,19 @@ shows update-in-place and replacement handling.
1. Branch off `main`: `git checkout -b feature/my-feature`
2. Open a PR targeting `main`.
-3. CI runs tests automatically — all checks must pass before merge.
-4. Keep PRs focused — one feature or fix per PR.
+3. CI runs tests automatically. All checks must pass before merge.
+4. Keep PRs focused: one feature or fix per PR.
5. Reference any related issues in the PR description.
-6. Keep at most **5 open PRs** at a time. A bot leaves an advisory note and an `over-pr-limit` label on PRs opened beyond that — nothing gets closed or blocked, but please land or close your existing PRs before opening more.
+6. Keep at most **5 open PRs** at a time. A bot leaves an advisory note and an `over-pr-limit` label on PRs opened beyond that. Nothing gets closed or blocked, but please land or close your existing PRs before opening more.
Docker images are never built on contributor PRs, so merging to `main` is always cheap.
## Release Process (maintainers)
+Stable releases ship on the **1st and 3rd Tuesday of each month**. Merging to `main` does
+not cut a release: the change rides the next train, and reaches the `nightly` image on the
+next nightly build.
+
Releases are cut from `main` with the **Release Cut** workflow
(Actions → Release Cut → Run workflow). semantic-release analyzes the
Conventional Commits since the last tag, bumps `pom.xml`, regenerates
@@ -202,7 +206,7 @@ Conventional Commits since the last tag, bumps `pom.xml`, regenerates
push triggers the Docker publish pipeline. Use the `dry-run` input to
preview the next version and notes without releasing.
-`CHANGELOG.md` is generated — **do not edit it by hand**. Your Conventional
+`CHANGELOG.md` is generated. **Do not edit it by hand.** Your Conventional
Commit message is the changelog entry. Genuine corrections to the file
require the `changelog-edit` label on the PR.
diff --git a/docs/configuration/docker-images.md b/docs/configuration/docker-images.md
index c4fdf997fb..b55f2f70fa 100644
--- a/docs/configuration/docker-images.md
+++ b/docs/configuration/docker-images.md
@@ -4,23 +4,23 @@ Floci publishes images to [Docker Hub (`floci/floci`)](https://hub.docker.com/r/
Every image tag combines two independent choices: **what's inside** (variant) and **how stable it is** (channel).
-## Axis 1 — Variant (what's inside)
+## Axis 1: Variant (what's inside)
| Variant | Contents | When to use |
|---|---|---|
-| **Standard** | Floci native binary only | General use — CI, local dev, Testcontainers **(recommended)** |
+| **Standard** | Floci native binary only | General use: CI, local dev, Testcontainers **(recommended)** |
| **Compat** | Floci + Python 3 + AWS CLI + boto3 | Workflows that need AWS tooling available inside the container |
-The compat image is built on top of the standard image — startup time and memory footprint are identical. Only the image size increases.
+The compat image is built on top of the standard image, so startup time and memory footprint are identical. Only the image size increases.
-## Axis 2 — Channel (how stable)
+## Axis 2: Channel (how stable)
| Channel | Source | Published |
|---|---|---|
-| **Release** | Tagged version (e.g. `1.5.11`) | On every release |
-| **Nightly** | Tip of `main` | Every night at 22:00 CT |
+| **Release** | Tagged version (e.g. `1.7.0`) | 1st and 3rd Tuesday of each month |
+| **Nightly** | Tip of `main` | Every night at 23:00 CT |
-Release images are stable and recommended for most use cases. Nightly images track active development and may include unreleased changes.
+Release images are stable and recommended for most use cases. Between trains, `nightly` carries every merged fix from the following morning. Nightly images track active development and may include unreleased changes.
## Full Tag Matrix
@@ -33,7 +33,7 @@ Combining both axes gives the complete set of published tags:
| **Nightly (floating)** | `nightly` | `nightly-compat` |
| **Nightly (dated)** | `nightly-mmddyyyy` | `nightly-mmddyyyy-compat` |
-Dated nightly tags (e.g. `nightly-05022026`) are fixed and never move — use them for reproducible builds from `main`.
+Dated nightly tags (e.g. `nightly-05022026`) name one night's build of `main`. A same-day rerun of the nightly workflow republishes that day's tag, so for a build you can rely on not changing, pin a release version.
!!! warning
Nightly images may include unreleased or experimental changes. Use release tags in production-like environments.
@@ -41,16 +41,16 @@ Dated nightly tags (e.g. `nightly-05022026`) are fixed and never move — use th
## Quick Reference
```yaml title="docker-compose.yml"
-# Standard release — recommended
+# Standard release : recommended
image: floci/floci:latest
-# Compat release — includes AWS CLI and boto3
+# Compat release : includes AWS CLI and boto3
image: floci/floci:latest-compat
-# Pinned release — reproducible builds
-image: floci/floci:1.5.11
+# Pinned release : reproducible builds
+image: floci/floci:1.7.0
-# Nightly — track main
+# Nightly : track main
image: floci/floci:nightly
```
@@ -125,7 +125,7 @@ The compat image installs the following on top of the standard image:
- [AWS CLI](https://pypi.org/project/awscli/) (via pip)
- [boto3](https://pypi.org/project/boto3/) (via pip)
-The AWS CLI is pre-configured to talk to the local Floci endpoint — no `--endpoint-url` flag is needed in hook scripts:
+The AWS CLI is pre-configured to talk to the local Floci endpoint, so no `--endpoint-url` flag is needed in hook scripts:
```sh
#!/bin/sh
diff --git a/docs/contributing.md b/docs/contributing.md
index fb3ab071ac..667d58dbbd 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -2,13 +2,13 @@
Floci is MIT licensed and welcomes contributions of all kinds.
-**Join us on [Slack](https://join.slack.com/t/floci/shared_invite/zt-3tjn02s3q-A00kEjJ1cZxsg_imTfy6Cw)** — the fastest way to reach maintainers for questions, design tradeoffs, or feedback on an approach before you build it.
+**Join us on [Slack](https://join.slack.com/t/floci/shared_invite/zt-3tjn02s3q-A00kEjJ1cZxsg_imTfy6Cw)**: the fastest way to reach maintainers for questions, design tradeoffs, or feedback on an approach before you build it.
## Ways to Help
-- **Bug reports** — open a [GitHub issue](https://github.com/floci-io/floci/issues/new?template=bug_report.md) with a minimal reproduction
-- **Missing API actions** — open a [feature request](https://github.com/floci-io/floci/issues/new?template=feature_request.md)
-- **Pull requests** — new service actions, bug fixes, documentation improvements
+- **Bug reports**: open a [GitHub issue](https://github.com/floci-io/floci/issues/new?template=bug_report.md) with a minimal reproduction
+- **Missing API actions**: open a [feature request](https://github.com/floci-io/floci/issues/new?template=feature_request.md)
+- **Pull requests**: new service actions, bug fixes, documentation improvements
## Development Setup
@@ -30,7 +30,7 @@ mvn test -Dtest=SsmIntegrationTest#putParameter
## Commit Message Format
-This project uses [Conventional Commits](https://www.conventionalcommits.org/) — required for semantic-release to generate the changelog and version bumps automatically.
+This project uses [Conventional Commits](https://www.conventionalcommits.org/), required for semantic-release to generate the changelog and version bumps automatically.
> **The PR title is validated automatically by CI** and must follow this format, since it becomes the squash-merge commit message that semantic-release reads.
@@ -100,7 +100,13 @@ Quick summary:
- [ ] New or updated integration test added
- [ ] Commit messages follow Conventional Commits
-Please keep at most **5 open PRs** at a time — a bot leaves an advisory note (label `over-pr-limit`) on PRs opened beyond that. See [CONTRIBUTING.md](https://github.com/floci-io/floci/blob/main/CONTRIBUTING.md#pull-request-guidelines) for details.
+Please keep at most **5 open PRs** at a time. A bot leaves an advisory note (label `over-pr-limit`) on PRs opened beyond that. See [CONTRIBUTING.md](https://github.com/floci-io/floci/blob/main/CONTRIBUTING.md#pull-request-guidelines) for details.
+
+## Releases
+
+Stable releases ship on the **1st and 3rd Tuesday of each month**. Merging to `main` does not cut a release: the change rides the next train, and reaches the `nightly` image on the next nightly build.
+
+Maintainers cut releases from `main` with the Release Cut workflow, which runs semantic-release over the Conventional Commits since the last tag. That is why the commit type matters: `feat:` and `fix:` move the version, `docs:` and `chore:` do not. `CHANGELOG.md` is generated from those messages and is not edited by hand; a genuine correction goes in a PR carrying the `changelog-edit` label.
## Reporting Security Issues