See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.
JavaScript ai-codingarchitecture-diagramclaudeclaude-codeclaude-code-plugincodebase-visualizationcodexcodex-plugindeveloper-toolsonboardingopenaivibe-coding
Document branch, release and issue conventions
Hayden Smith9f98cd10ee2a
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.mdindex 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 changediff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 requests1. 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.mdindex 310611d..db5c7fb 100644--- a/docs/development.md+++ b/docs/development.md@@ -30,6 +30,7 @@ skills/floorplan/query-cli.mjs becomes floorplan/query.mjslogo.png, favicon.pngvendor/ bundled layout engine (elkjs) and fonts, with their licenses+tests/ regression tests and the sample projects they mapdocs/ 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 viewerFiles 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.