Skip to content

docs: say when releases are cut, and that there is no fixed cadence #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hectorvent merged 1 commit into from
Sep 1, 2026
Merged

docs: say when releases are cut, and that there is no fixed cadence #21

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 18 additions & 15 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ Thank you for your interest in contributing! `floci-cli` is a community-driven p

## Ways to Contribute

- **Bug reports** — open an issue with the CLI version (`floci version`), OS/arch, and the exact command + output
- **Feature requests** — open an issue describing the workflow you need (keep the [scope rules](#scope) in mind)
- **Pull requests** — bug fixes, new commands, diagnostics checks, or improvements
- **Bug reports**: open an issue with the CLI version (`floci version`), OS/arch, and the exact command + output
- **Feature requests**: open an issue describing the workflow you need (keep the [scope rules](#scope) in mind)
- **Pull requests**: bug fixes, new commands, diagnostics checks, or improvements

## Getting Started

Expand All @@ -22,7 +22,7 @@ If you need to install a JDK, [SDKMAN](https://sdkman.io/) is a convenient optio
```bash
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install java 25-graal # GraalVM — also covers the plain JDK requirement
sdk install java 25-graal # GraalVM : also covers the plain JDK requirement
```

### Build & Test
Expand All @@ -46,7 +46,7 @@ java -jar target/floci.jar doctor
java -jar target/floci.jar stop
```

**If your change touches Jackson serialization or adds a dependency, build and run the native binary at least once** — reflection that works on the JVM can fail under `native-image`. See the Native Image Constraints section of [AGENTS.md](AGENTS.md).
**If your change touches Jackson serialization or adds a dependency, build and run the native binary at least once**: reflection that works on the JVM can fail under `native-image`. See the Native Image Constraints section of [AGENTS.md](AGENTS.md).

## Architecture

Expand All @@ -73,9 +73,9 @@ ln -s AGENTS.md GEMINI.md

## Scope

`floci-cli` manages Floci itself — lifecycle, config, diagnostics, state. Out of scope (PRs in these areas will be declined):
`floci-cli` manages Floci itself: lifecycle, config, diagnostics, state. Out of scope (PRs in these areas will be declined):

- Cloud resource commands (creating buckets, tables, topics, …) — that's the job of `aws`/`gcloud`/`az` pointed at the emulator
- Cloud resource commands (creating buckets, tables, topics, …): that's the job of `aws`/`gcloud`/`az` pointed at the emulator
- Telemetry, TUIs, or Floci Cloud commands
- Client-side snapshot behavior beyond the server's `/_floci/snapshots/*` API

Expand All @@ -87,9 +87,9 @@ This project uses [Conventional Commits](https://www.conventionalcommits.org/).
<type>[optional scope]: <description>
```

- **type** — lowercase, from the table below
- **scope** — optional, identifies the command or area (e.g. `start`, `doctor`, `update`, `gcp`)
- **description** — imperative mood, no trailing period
- **type**: lowercase, from the table below
- **scope**: optional, identifies the command or area (e.g. `start`, `doctor`, `update`, `gcp`)
- **description**: imperative mood, no trailing period
- Append `!` before the colon for a breaking change: `feat(cli)!:`

| Type | When to use |
Expand All @@ -115,31 +115,34 @@ Do not include `Co-Authored-By` trailers for AI tools in commit messages. Attrib

## Changelog

`CHANGELOG.md` is generated by [semantic-release](https://github.com/semantic-release/semantic-release) from Conventional Commit messages — **do not edit it by hand**. Your commit message *is* the changelog entry, so write it from the user's point of view (what was broken / what's new, not how it was implemented). Genuine corrections to the file (typos in history, security notes) require the `changelog-edit` label on the PR.
`CHANGELOG.md` is generated by [semantic-release](https://github.com/semantic-release/semantic-release) from Conventional Commit messages. **Do not edit it by hand**. Your commit message *is* the changelog entry, so write it from the user's point of view (what was broken / what's new, not how it was implemented). Genuine corrections to the file (typos in history, security notes) require the `changelog-edit` label on the PR.

## Pull Request Guidelines

1. Branch off `main`: `git checkout -b feature/my-feature`
2. Open a PR targeting `main`
3. CI runs the JVM test suite and a linux/arm64 native smoke test — all checks must pass before merge
4. Keep PRs focused — one feature or fix per PR
3. CI runs the JVM test suite and a linux/arm64 native smoke test. All checks must pass before merge
4. Keep PRs focused: one feature or fix per PR
5. Update `README.md` in the same PR if you add or change a command or flag
6. Reference related issues in the PR description

### Testing policy

- PRs that introduce new behavior must include tests validating that behavior
- Bug-fix PRs should include a regression test whenever the bug can be covered realistically
- Docs, formatting, and low-risk internal refactors may not need new tests — but the existing suite must pass
- Docs, formatting, and low-risk internal refactors may not need new tests, but the existing suite must pass
- If a PR includes no new tests, explain why in the description

## Release Process (maintainers)

Releases are cut when there is something worth shipping. Unlike the emulators, floci-cli is
not on a fixed train.

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 `<version>` in `pom.xml`, regenerates `CHANGELOG.md`, commits, tags, and publishes the GitHub Release. Use the `dry-run` input to preview the next version and release notes without releasing anything.

The tag push then triggers `release.yml` exactly as a manual tag push did before: native binaries for linux/amd64, linux/arm64, darwin/amd64, darwin/arm64 and windows/amd64, plus the fat JAR, published as a GitHub Release with `sha256sums.txt`. A successful release triggers `homebrew-bump.yml`, which opens a version-bump PR against the Homebrew tap automatically.

Nothing is published on PR merge — only a release cut produces artifacts.
Nothing is published on PR merge: only a release cut produces artifacts.

## Reporting Security Issues

Expand Down