Skip to content

See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.

Document branch, release and issue conventions

Hayden Smith9f98cd10ee2a
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index fa2845c..ee643a3 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -12,5 +12,6 @@
- [ ] Anything the map shows people is in plain language
- [ ] No secret values stored or printed
- [ ] No details of a real private project in code, comments, docs or screenshots
+- [ ] `node --test "tests/**/*.test.mjs"` passes
- [ ] `claude plugin validate .` passes
- [ ] `CHANGELOG.md` updated, if people will notice the change
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4674655..9725f47 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -21,13 +21,20 @@ Open an issue describing what you were trying to do and what got in the way. Plu
## Pull requests
1. Read [Developing Floorplan](docs/development.md) for the layout and how to test a local copy.
-2. Keep changes focused, and follow the guidelines there:
+2. Branch from `main` with a name like `fix/<issue number>-short-name` or `feat/short-name`, and link the issue in the PR.
+3. Keep changes focused, and follow the guidelines there:
- no dependencies;
- plain language in anything the map shows;
- never store or print secret values;
- keep examples generic.
-3. Try your change on at least one real project, and say which kind in the PR.
-4. If you changed behaviour people will notice, add a line to `CHANGELOG.md` under an "Unreleased" heading at the top.
-5. Run `claude plugin validate .` before opening the PR.
+4. Try your change on at least one real project, and say which kind in the PR. If you fixed something Floorplan detects wrongly, add a small sample to `tests/` that shows it.
+5. If you changed behaviour people will notice, add a line to `CHANGELOG.md` under an "Unreleased" heading at the top.
+6. Before opening the PR, run:
+ ```bash
+ node --test "tests/**/*.test.mjs"
+ claude plugin validate .
+ ```
+
+Pull requests are merged with their commits and authorship kept, and you're credited in the changelog and release notes.
By contributing, you agree that your contributions are licensed under the [MIT License](LICENSE).
diff --git a/docs/development.md b/docs/development.md
index 310611d..db5c7fb 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -30,6 +30,7 @@ skills/floorplan/
query-cli.mjs becomes floorplan/query.mjs
logo.png, favicon.png
vendor/ bundled layout engine (elkjs) and fonts, with their licenses
+tests/ regression tests and the sample projects they map
docs/ these guides
```
@@ -54,6 +55,14 @@ node skills/floorplan/scripts/open.mjs /path/to/project
`build.mjs` needs a `floorplan/architecture.json` in the project, so run the skill once first, or write a small one by hand ([schema](../skills/floorplan/references/schema.md)).
+## Tests
+
+```bash
+node --test "tests/**/*.test.mjs"
+```
+
+Each test maps a small sample project from `tests/fixtures/` and checks the result, using Node's built-in test runner. When you fix a bug in what Floorplan detects, add a sample that shows it, and check the test fails without your fix.
+
## Extending the viewer
Files in `skills/floorplan/assets/ui/` are inlined into every map, in name order. They talk to the viewer only through `window.Floorplan`, which offers:
@@ -72,16 +81,56 @@ Files in `skills/floorplan/assets/ui/` are inlined into every map, in name order
- **Never store or print secret values.** Health findings record where a secret is and a masked hint, never the value.
- **Keep examples generic.** Code comments, docs and prompts must not describe any real private project.
-## Releasing
+## Maintaining
+
+### Branches and commits
+
+- `main` is always releasable. Every change reaches it through its own branch, merged with a merge commit (`git merge --no-ff`), so each change reads as one unit in the history.
+- Name branches by what they are, with the issue number when there is one:
+ - `fix/4-fastapi-annotated-guards`
+ - `feat/codex-support`
+ - `docs/…`, `chore/…`
+
+ A branch made with GitHub's **Create a branch** button on an issue (`2-reaching-outside-repo`) is fine too.
+- Commit messages start with a short summary in the imperative ("Bundle the layout engine"), and the body says why.
+ - `Fixes #N` in a commit or merge message closes the issue when it reaches `main`.
+ - `Refs #N` links it without closing.
+- **Contributors' pull requests keep their commits and authorship.** Merge them with a merge commit ("Merge pull request #N from user/branch"), and resolve `CHANGELOG.md` conflicts by keeping both entries.
+- Delete branches once merged.
+
+### Versions and the changelog
+
+- Versions follow [semantic versioning](https://semver.org). Before 1.0:
+ - a patch (0.1.x) for fixes and small improvements;
+ - a minor version (0.x.0) for new features, or anything that changes what people install or run.
+- **Users only receive an update when the version changes**, so release fixes promptly rather than leaving them on `main`.
+- Every change people will notice adds a line under `## Unreleased` at the top of `CHANGELOG.md`:
+ - in plain language;
+ - crediting whoever reported or fixed it, e.g. "Reported by @name in #1, fixed by @name in #3".
+
+### Releasing
-1. Update `CHANGELOG.md`.
-2. Bump `version` in `.claude-plugin/plugin.json`. Users only receive an update when the version changes.
-3. Check the manifests, including the official plugin directory's requirements:
+1. On an up-to-date `main`, run the tests and check the manifests, including the official plugin directory's requirements:
```bash
+ node --test "tests/**/*.test.mjs"
claude plugin validate . --profile directory
```
-4. Commit, then create the release tag, which checks that `plugin.json` and the marketplace entry agree:
+2. Bump `version` in `.claude-plugin/plugin.json` and the version badge in `README.md`.
+3. Rename `## Unreleased` in `CHANGELOG.md` to `## X.Y.Z (YYYY-MM-DD)`.
+4. Commit as `Floorplan X.Y.Z: <one-line headline>` and push `main`.
+5. Tag and push the tag. This also checks that `plugin.json` and the marketplace entry agree:
```bash
- claude plugin tag
- git push --follow-tags
+ claude plugin tag . -m "Floorplan %s" --push
```
+6. On GitHub, publish a release from the tag (`floorplan--vX.Y.Z`), titled `Floorplan X.Y.Z`, with that version's changelog section as its notes.
+7. Reply on every issue and pull request the release fixes: what changed, the version, and how to get it (`claude plugin update floorplan@floorplan`).
+
+### Issues and pull requests
+
+- Reply to new issues within a few days, even if only to say you've seen them.
+ - Label each one (`bug`, `enhancement`, `question`).
+ - Assign yourself when you pick it up.
+- Ask for the shape of a problem, never for private code, secrets or screenshots of a private map.
+- Thank contributors, and credit them in the changelog and release notes.
+- Close an issue with a comment that names the release containing the fix.
+- Security reports go through [SECURITY.md](../SECURITY.md), privately. Don't discuss them in public issues until a fix is released.