Skip to content

docs: update RELEASING.md for strict PR-based release flow #49

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JohnRDOrazio merged 1 commit into from
Apr 9, 2026
Merged

docs: update RELEASING.md for strict PR-based release flow #49

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 33 additions & 19 deletions RELEASING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,11 +87,15 @@ These three jobs run on pushes to `main` and `dev` (and on PRs). The publish job

Releases follow a Weblate-inspired workflow. All commands below are run from the `ontokit-api/` directory.

### 1. Prepare the release (on `dev`)
### 1. Prepare the release (on a release branch)

Create a release branch from `dev` and run the prepare script:

```bash
git checkout dev
git checkout dev && git pull
git checkout -b release/0.2.0
python scripts/prepare-release.py
git push -u origin release/0.2.0
```

This script:
Expand All @@ -100,22 +104,25 @@ This script:
3. Writes the updated version back to `ontokit/version.py`.
4. Creates a git commit: `chore: releasing 0.2.0`.

### 2. Merge into `main` and tag
### 2. Open a PR to `main`

```bash
git checkout main
git merge dev
git tag -s ontokit-0.2.0
gh pr create --base main --title "Release 0.2.0" \
--body "Merge release 0.2.0 into main for tagging."
```

Tags must match the pattern `ontokit-*` to trigger the publish pipeline.
Wait for CI (lint, test, build) to pass and merge the PR.

### 3. Push `main` and the tag
### 3. Tag the release

```bash
git push origin main --tags
git checkout main && git pull
git tag -s ontokit-0.2.0
git push origin --tags
```

Tags must match the pattern `ontokit-*` to trigger the publish pipeline.

### 4. CI publishes automatically

When the tag reaches GitHub, the CI workflow runs the lint/test/build jobs and then three publish jobs in parallel:
Expand All @@ -129,27 +136,34 @@ When the tag reaches GitHub, the CI workflow runs the lint/test/build jobs and t

### 5. Set the next development version (on `dev`)

Create a branch from `dev`, bump the version, and open a PR:

```bash
git checkout dev
git checkout dev && git pull
git checkout -b chore/next-dev-version
python scripts/set-version.py 0.3.0
git push origin dev
git push -u origin chore/next-dev-version
gh pr create --base dev --title "chore: set version to 0.3.0-dev" \
--body "Start the next development cycle."
```

This script:
1. Updates `ontokit/version.py` to `0.3.0-dev`.
2. Creates a git commit: `chore: setting version to 0.3.0-dev`.

Merge the PR to start the next development cycle.

### Quick reference

```
dev dev
│ │
│ prepare-release.py tag & push │
│ (strips -dev) (on main) │
│ │ │ ┌─ PyPI │ set-version.py 0.4.0
▼ ▼ ▼ │ │ │
0.3.0-dev ──▸ 0.3.0 ──merge──▸ main ──tag──▸ CI ────┼─ GitHub Release│ ▼
└─ GHCR └── 0.4.0-dev
dev dev
│ │
│ release/0.2.0 branch PR → main tag │
│ prepare-release.py (CI gate) (push) │
│ │ │ │ ┌─ PyPI │ chore/next-dev-version
▼ ▼ ▼ ▼ │ │ set-version.py 0.3.0
0.2.0-dev ──▸ 0.2.0 ──PR──▸ main (merge) ──tag──▸ CI ──────┼─ GitHub │ PR → dev
└─ GHCR └── 0.3.0-dev
```
Comment on lines 158 to 167
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Apr 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language identifier to fenced code block.

The fenced code block should specify a language identifier to satisfy markdown linting rules. For ASCII art diagrams, use text.

🔧 Proposed fix 
-```
+```text
 dev                                                                       dev
  │                                                                         │

As per coding guidelines, static analysis flagged: "Fenced code blocks should have a language specified (MD040, fenced-code-language)".

🧰 Tools
🪛 markdownlint-cli2 (0.22.0)

[warning] 158-158: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@RELEASING.md` around lines 158 - 167, The fenced ASCII-art code block shown
(the triple-backtick block containing the release diagram starting with "dev    
dev") lacks a language identifier; update the opening fence from ``` to ```text
so the block becomes a labeled text block (e.g., change the opening fence of the
ASCII diagram to ```text) to satisfy MD040/fenced-code-language linting.


## Patch releases
Expand Down
Loading