mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-09-30 12:39:42 +02:00
Codeman maintainer
f3cb7696f0
30 pages covering install, concepts, the dashboard, the agent CLIs, unattended
runs, remote and Docker cases, security and the HTTP API, plus a sidebar and a
footer. The wiki repo has no CI and no review, so docs/wiki is the source of
truth and .github/workflows/wiki-sync.yml mirrors it on every push to master.
The workflow refuses to mirror when docs/wiki is missing or holds no pages,
because it deletes before it copies and would otherwise publish the deletion of
every page. The footer carries a {{VERSION}} placeholder stamped at publish
time rather than a hand-written version, which went stale on every release.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
73 lines
3.1 KiB
Markdown
73 lines
3.1 KiB
Markdown
# Versioning
|
|
|
|
Codeman follows [semantic versioning](https://semver.org/). This page says what the version
|
|
number actually promises, which matters if you are building anything against Codeman.
|
|
|
|
## Covered by the version number
|
|
|
|
Breaking any of these after 1.0 requires a **major** bump:
|
|
|
|
1. **The CLI.** Command names, documented flags, and their behaviour. The npm package is
|
|
`aicodeman` and installs both the `aicodeman` and `codeman` commands; renaming either is
|
|
breaking.
|
|
2. **The HTTP API and SSE channel**, served under `/api/v1` with the uniform envelope and
|
|
conventional status codes. Endpoint paths, the envelope, `errorCode` values, and SSE event
|
|
names are all stable.
|
|
3. **Documented deployment environment variables**: `CODEMAN_PASSWORD`, `CODEMAN_USERNAME`,
|
|
`CODEMAN_HOST`, `CODEMAN_PORT`, `CODEMAN_INSTANCE`, `CODEMAN_ALLOWED_HOSTS`,
|
|
`CODEMAN_DATA_DIR`, `CODEMAN_TMUX_SOCKET`, plus the `--host`, `--port`, and `--https`
|
|
flags.
|
|
4. **The published `xterm-zerolag-input` library**, on its own independent version line.
|
|
Codeman reaching 1.0 says nothing about that package's version.
|
|
|
|
Additive changes are **not** breaking: new endpoints, new optional fields, new error codes,
|
|
new SSE events. Genuinely breaking API changes would ship under a new prefix rather than
|
|
changing `/api/v1`.
|
|
|
|
## Not covered
|
|
|
|
These can change in a minor or even patch release:
|
|
|
|
1. **The `~/.codeman/` state file formats.** Migrations are made on a best-effort basis and
|
|
have been done across renames, but the on-disk shape is not a contract. Do not write
|
|
tooling against it.
|
|
2. **Internal TypeScript modules.** The npm package is CLI-only. There is no stable library
|
|
entry point, and importing it programmatically is unsupported.
|
|
3. **Experimental and opt-in features**, whatever the app's version: gesture control, agent
|
|
teams, and anything labelled experimental in the UI or docs.
|
|
|
|
## Deprecation
|
|
|
|
- Additive changes are preferred over breaking ones.
|
|
- A covered surface slated for removal is deprecated first: it keeps working for at least one
|
|
minor release, with a runtime warning and a changelog note pointing at the replacement,
|
|
then is removed in the next major.
|
|
- Backwards-compatibility shims are kept until a major boundary.
|
|
|
|
## Releases
|
|
|
|
Releases are managed with changesets. Every release:
|
|
|
|
- Bumps the version and updates
|
|
[`CHANGELOG.md`](https://github.com/Ark0N/Codeman/blob/master/CHANGELOG.md).
|
|
- Publishes to npm as `aicodeman`.
|
|
- Cuts a GitHub release, tagged `codeman@X.Y.Z`.
|
|
- **Credits its contributors and bug reporters by name** in the release notes.
|
|
|
|
There is no fixed cadence. Patches ship when fixes are ready, which in practice is often.
|
|
|
|
## Which version am I on?
|
|
|
|
```bash
|
|
codeman --version
|
|
```
|
|
|
|
Or **App Settings → Updates**, which also checks for a newer one and can install it. See
|
|
[Running As A Service](Running-As-A-Service).
|
|
|
|
## Read next
|
|
|
|
- [HTTP API](HTTP-API) - the stable API surface itself.
|
|
- [Contributing](Contributing) - how changes get made.
|
|
- [`docs/versioning-policy.md`](https://github.com/Ark0N/Codeman/blob/master/docs/versioning-policy.md) - the authoritative statement.
|