diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5c5303a1..ddf66ab2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,11 +40,22 @@ If you accidentally based your branch off another feature branch, fix it by cher ### Expectations +- Open a PR as **Draft** early (especially for multi-step work) so progress is visible and local changes aren’t lost. - Keep PRs **small and focused** when possible. - Include a clear description of the change and why it’s needed. - Add/adjust tests when behavior changes. - Update docs when contributor-facing or operator-facing behavior changes. +### Draft PR policy + +- Start as **Draft** when: + - the PR is incomplete, + - CI is expected to fail, + - or you need early feedback on direction. +- Mark **Ready for review** when: + - `make check` is green locally (or you’ve explained why it can’t be), and + - the description includes repro/verification notes. + ### Local checks From repo root, the closest “CI parity” command is: diff --git a/README.md b/README.md index 9817e228..c37fc4c6 100644 --- a/README.md +++ b/README.md @@ -112,6 +112,15 @@ make setup make check ``` +## Contributing / PR workflow + +- Contribution guide: [`CONTRIBUTING.md`](./CONTRIBUTING.md) +- Preferred flow: open a **Draft PR early**, then iterate until `make check` is green. + +## Releasing + +- Maintainer checklist: [Release checklist](./docs/release/README.md) + ## License This project is licensed under the MIT License. See [`LICENSE`](./LICENSE). diff --git a/docs/README.md b/docs/README.md index 80a9fbe9..1e161f96 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,6 +10,7 @@ This folder is the starting point for Mission Control documentation. - [Deployment](./deployment/README.md) - [Production notes](./production/README.md) - [Troubleshooting](./troubleshooting/README.md) +- [Release checklist](./release/README.md) - [Gateway WebSocket protocol](./openclaw_gateway_ws.md) ## Status diff --git a/docs/release/README.md b/docs/release/README.md new file mode 100644 index 00000000..baf46381 --- /dev/null +++ b/docs/release/README.md @@ -0,0 +1,101 @@ +# Release checklist (maintainers) + +This project does not yet have a fully automated release pipeline. + +Use this checklist for **manual releases** and as a place to evolve the process over time. + +## Before you start + +- [ ] You have maintainer permissions on `abhi1693/openclaw-mission-control` +- [ ] You know which **scope** you’re releasing: + - [ ] backend-only change + - [ ] frontend-only change + - [ ] infra/docs-only change + - [ ] full release + +## 1) Pick the release commit + +- [ ] Ensure you’re on the latest `master`: + +```bash +git fetch origin +git checkout master +git reset --hard origin/master +``` + +- [ ] Identify the commit SHA you want to release (usually `origin/master`). + +## 2) Verify CI + local checks + +- [ ] CI is green on the target commit. +- [ ] Run the local CI-parity checks: + +```bash +make setup +make check +make docs-check +``` + +## 3) Smoke test (recommended) + +If the change affects runtime behavior (API/UI/auth), do a quick smoke test using the compose stack. + +```bash +cp .env.example .env +# Configure .env (see repo README for auth mode notes) + +docker compose -f compose.yml --env-file .env up -d --build + +after_up() { + echo "Frontend: http://localhost:3000" + echo "Backend health: http://localhost:8000/healthz" +} + +after_up +``` + +- [ ] Validate basic flows (at minimum): + - [ ] frontend loads + - [ ] backend `/healthz` returns 200 + - [ ] auth mode behaves as expected (local or clerk) + +## 4) Prepare release notes + +There is no enforced changelog format yet. + +Choose one: +- [ ] GitHub Release notes (recommended for now) +- [ ] `CHANGELOG.md` (TODO: adopt Keep a Changelog) + +Minimum release notes: +- [ ] Summary of key changes +- [ ] Any config changes / env var changes +- [ ] Any DB migration notes +- [ ] Known issues + +## 5) Tag + publish + +**TODO:** confirm the desired tag format (e.g. `v0.1.0`) and whether releases should be created from tags or from `master`. + +Suggested manual flow: + +```bash +# Example (adjust once tag conventions are decided) +git tag -a v0.0.0 -m "Release v0.0.0" +git push origin v0.0.0 +``` + +- [ ] Create a GitHub Release from the tag +- [ ] Paste the release notes + +## 6) Post-release + +- [ ] Monitor new issues for regressions +- [ ] If you changed public behavior, ensure docs are updated (README + docs pages) + +## Notes / follow-ups + +- Consider adding: + - automated versioning (changesets / semantic-release) + - release workflow in `.github/workflows/release.yml` + - a `CHANGELOG.md`