Skip to content

Commit b8ab20f

Browse files
committed
docs: add versioning guide, fix impersonal tone, codify writing style rule
- Add versioning (SemVer), pre-release labels, and release process to CI docs - Rewrite docs to use impersonal language throughout - Add writing style rule to CLAUDE.md: no "you/your/we/our" in docs/comments
1 parent 0a1ae27 commit b8ab20f

File tree

2 files changed

+65
-3
lines changed

2 files changed

+65
-3
lines changed

CLAUDE.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,4 +136,5 @@ See `docs/` for the full documentation index.
136136
## Rules for Generated Code
137137

138138
- Comments must be appropriate for an open source project with multiple contributors — they must NOT be aimed at any individual and must be timeless.
139+
- **Documentation and comments must use impersonal language.** No "you", "your", "we", or "our" — write for a general audience, not a specific person. Use passive voice or third person where needed (e.g., "Not all stages are required" instead of "You don't need to use all stages").
139140
- Never co-author commits with Claude.

docs/ci/README.md

Lines changed: 64 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -69,13 +69,74 @@ With warm caches, typical CI times are:
6969

7070
Cold cache (first run or after Cargo.lock changes): ~2-3 minutes per job.
7171

72+
## Versioning
73+
74+
FerrumC follows [Semantic Versioning](https://semver.org/) (SemVer).
75+
76+
### Version Format
77+
78+
**`MAJOR.MINOR.PATCH`** — e.g., `1.4.2`
79+
80+
| Component | When to bump | Example |
81+
|---|---|---|
82+
| **MAJOR** | Breaking changes — config format changes, protocol rewrites, removed features | `1.0.0``2.0.0` |
83+
| **MINOR** | New features, backwards compatible — new commands, new packet support, new config options | `1.0.0``1.1.0` |
84+
| **PATCH** | Bug fixes only — no new features, no breaking changes | `1.0.0``1.0.1` |
85+
86+
### Pre-release Versions
87+
88+
A `0.x.x` major version means the project is not yet stable — any release can contain breaking changes.
89+
90+
Pre-release labels are appended with a hyphen to indicate the release isn't final:
91+
92+
| Label | Meaning | Example |
93+
|---|---|---|
94+
| `alpha` | Early preview. Features incomplete, expect breakage. | `v0.2.0-alpha.1` |
95+
| `beta` | Feature complete but not fully tested. | `v0.2.0-beta.1` |
96+
| `rc` | Release Candidate. "We think this is ready, testing before making it official." | `v0.2.0-rc1` |
97+
| *(none)* | Final release. Stable, tested, ready for use. | `v0.2.0` |
98+
99+
The typical progression is: **alpha → beta → rc → release**. Not all stages are required — most releases go straight from development to `rc` → final, or skip `rc` entirely for small patches.
100+
101+
If a bug is found in `rc1`, the fix gets tagged as `rc2`. Once the RC is validated, the final version is tagged (same commit or a new one).
102+
103+
### Versioning in Practice
104+
105+
FerrumC is currently at `0.1.0` (pre-stable). A realistic release flow looks like:
106+
107+
1. Development happens on `master`, PRs get merged.
108+
2. A set of changes is deemed worth releasing.
109+
3. Tag `v0.1.0-rc1` to test the release pipeline and binaries.
110+
4. If everything works, tag `v0.1.0` as the final release.
111+
5. Bug fix needed? Fix on master, tag `v0.1.1`.
112+
6. New feature? Tag `v0.2.0`.
113+
7. Massive breaking change (stable protocol, config rewrite)? Tag `v1.0.0`.
114+
72115
## Creating a Release
73116

74117
1. Ensure `master` is in a releasable state (CI green).
75-
2. Tag the commit: `git tag v1.0.0`
76-
3. Push the tag: `git push origin v1.0.0`
118+
2. Tag the commit:
119+
```bash
120+
git tag v0.1.0 # final release
121+
git tag v0.1.0-rc1 # release candidate (for testing)
122+
```
123+
3. Push the tag:
124+
```bash
125+
git push origin v0.1.0
126+
```
77127
4. The release workflow runs automatically: validate → build (4 platforms) → publish GitHub Release.
78-
5. If the build fails on any platform, fix the issue and create a new tag.
128+
5. If validation or build fails, fix the issue on master, then tag again (e.g., `v0.1.0-rc2`).
129+
130+
### Deleting a Bad Tag
131+
132+
To delete a tag that was pushed by mistake or needs to be redone:
133+
134+
```bash
135+
git tag -d v0.1.0-rc1 # delete locally
136+
git push origin :refs/tags/v0.1.0-rc1 # delete from remote
137+
```
138+
139+
Then delete the draft/failed GitHub Release from the Releases page if one was created.
79140

80141
## Suppressed Advisories
81142

0 commit comments

Comments
 (0)