diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7995488..459796b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 @@ -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 @@ -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 @@ -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 @@ -87,9 +87,9 @@ This project uses [Conventional Commits](https://www.conventionalcommits.org/). [optional scope]: ``` -- **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 | @@ -115,14 +115,14 @@ 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 @@ -130,16 +130,19 @@ Do not include `Co-Authored-By` trailers for AI tools in commit messages. Attrib - 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 `` 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