Skip to content

Commit f98f34f

Browse files
petercrockerpetercrocker
committed
docs: add release publishing documentation to README
Document the three methods for publishing releases to PyPI: - Automated release via PR labels and GitHub Release publishing - Manual GitHub Release creation - Manual workflow dispatch for emergency releases Include PR labeling guide, troubleshooting section, and workflow reference.
1 parent b39462e commit f98f34f

File tree

1 file changed

+178
-0
lines changed

1 file changed

+178
-0
lines changed

‎README.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,181 @@
1515
Infrahub Sync is a versatile Python package that synchronizes data between a source and a destination system. It builds on the robust capabilities of `diffsync` to offer flexible and efficient data synchronization across different platforms, including Netbox, Nautobot, and Infrahub. This package features a Typer-based CLI for ease of use, supporting operations such as listing available sync projects, generating diffs, and executing sync processes.
1616

1717
For comprehensive documentation on using Infrahub Sync, visit the [official Infrahub Sync documentation](https://docs.infrahub.app/sync/)
18+
19+
## Publishing a Release
20+
21+
This section documents how to publish new releases of `infrahub-sync` to PyPI.
22+
23+
### Overview
24+
25+
The project uses an automated release system powered by GitHub Actions. There are three ways to publish a release:
26+
27+
1. **Automated Release** (recommended for regular releases)
28+
2. **Manual GitHub Release** (for controlled releases)
29+
3. **Manual Workflow Dispatch** (for emergency or custom releases)
30+
31+
### Prerequisites
32+
33+
Before publishing, ensure:
34+
35+
- You have write access to the repository
36+
- The `PYPI_TOKEN` secret is configured in repository settings
37+
- The `GH_INFRAHUB_BOT_TOKEN` secret is configured (for automated releases)
38+
39+
### Method 1: Automated Release (Recommended)
40+
41+
This is the standard release flow. Releases are triggered automatically when PRs are merged to `main` or `stable` branches.
42+
43+
#### Step 1: Label Your Pull Requests
44+
45+
Apply appropriate labels to PRs before merging. Labels determine the version bump:
46+
47+
| Label | Version Bump | Use When |
48+
| ---------------------------------------------------------------------- | ---------------------- | ---------------------------- |
49+
| `changes/major`, `type/breaking-change` | Major (1.0.0 → 2.0.0) | Breaking API changes |
50+
| `changes/minor`, `type/feature`, `type/refactoring` | Minor (1.0.0 → 1.1.0) | New features, refactoring |
51+
| `changes/patch`, `type/bug`, `type/housekeeping`, `type/documentation` | Patch (1.0.0 → 1.0.1) | Bug fixes, docs, maintenance |
52+
53+
PRs are auto-labeled based on title patterns:
54+
55+
- Title contains `fix` → `type/bug`
56+
- Title contains `enhance`, `improve`, or `feature` → `type/feature`
57+
- Title contains `chore` → `ci/skip-changelog` (excluded from release notes)
58+
59+
#### Step 2: Merge to Main
60+
61+
Merge your labeled PR to the `main` branch. The automation will:
62+
63+
1. Calculate the next version based on PR labels
64+
2. Update `pyproject.toml` with the new version
65+
3. Update `poetry.lock`
66+
4. Commit changes as `chore(release): v{VERSION} [skip ci]`
67+
5. Create/update a draft GitHub Release with auto-generated release notes
68+
69+
#### Step 3: Publish the GitHub Release
70+
71+
1. Navigate to the repository's **Releases** page
72+
2. Find the draft release created by Release Drafter
73+
3. Review the auto-generated release notes
74+
4. Edit if needed (add context, highlights, migration notes)
75+
5. Click **Publish release**
76+
77+
Publishing the release triggers the PyPI upload automatically.
78+
79+
### Method 2: Manual GitHub Release
80+
81+
Use this method when you want full control over the release timing and notes.
82+
83+
#### Step 1: Update the Version
84+
85+
Update the version in `pyproject.toml`:
86+
87+
```bash
88+
poetry version <major|minor|patch|X.Y.Z>
89+
poetry lock
90+
```
91+
92+
Commit and push the changes:
93+
94+
```bash
95+
git add pyproject.toml poetry.lock
96+
git commit -m "chore(release): v$(poetry version -s)"
97+
git push origin main
98+
```
99+
100+
#### Step 2: Create a GitHub Release
101+
102+
1. Go to **Releases** → **Draft a new release**
103+
2. Click **Choose a tag** and create a new tag matching your version (e.g., `1.6.0`)
104+
3. Set the target to `main` branch
105+
4. Add a release title (e.g., `1.6.0`)
106+
5. Write release notes describing the changes
107+
6. Click **Publish release**
108+
109+
This triggers the `trigger-release.yml` workflow, which publishes to PyPI.
110+
111+
### Method 3: Manual Workflow Dispatch
112+
113+
Use this for emergency releases or when you need to bypass the standard flow.
114+
115+
#### Via GitHub UI
116+
117+
1. Go to **Actions** → **Publish Infrahub Sync Package**
118+
2. Click **Run workflow**
119+
3. Configure the inputs:
120+
- `version`: The version string (e.g., `1.6.0`) - optional, for labeling
121+
- `publish`: Set to `true` to publish to PyPI (default: `false`)
122+
- `runs-on`: OS for the runner (default: `ubuntu-22.04`)
123+
4. Click **Run workflow**
124+
125+
#### Via GitHub CLI
126+
127+
```bash
128+
gh workflow run workflow-publish.yml \
129+
--field version="1.6.0" \
130+
--field publish=true
131+
```
132+
133+
**Important:** When using workflow dispatch, ensure `pyproject.toml` already has the correct version, as this method builds from the current code state.
134+
135+
### Release Notes
136+
137+
Release notes are auto-generated based on merged PRs and their labels:
138+
139+
| Category | Labels |
140+
| -------------------- | --------------------------------------------------- |
141+
| Breaking Changes | `changes/major` |
142+
| Minor Changes | `changes/minor`, `type/feature`, `type/refactoring` |
143+
| Patch & Bug Fixes | `type/bug`, `changes/patch` |
144+
| Documentation Change | `type/documentation` |
145+
146+
PRs with these labels are excluded from release notes:
147+
148+
- `ci/skip-changelog`
149+
- `type/duplicate`
150+
151+
### Verifying a Release
152+
153+
After publishing:
154+
155+
1. **Check PyPI**: Visit [pypi.org/project/infrahub-sync](https://pypi.org/project/infrahub-sync/) to confirm the new version is available
156+
2. **Check GitHub Actions**: Ensure the publish workflow completed successfully
157+
3. **Test Installation**:
158+
159+
```bash
160+
pip install infrahub-sync==<new-version>
161+
infrahub-sync --version
162+
```
163+
164+
### Troubleshooting
165+
166+
#### Release workflow skipped
167+
168+
The automated release is skipped when:
169+
170+
- The commit author is `opsmill-bot` with a `chore` prefix (prevents recursive releases)
171+
- No version bump is detected (no labeled PRs since last release)
172+
- Changes are only in the `docs/` directory
173+
174+
#### PyPI upload failed
175+
176+
Common causes:
177+
178+
- `PYPI_TOKEN` secret is missing or invalid
179+
- Version already exists on PyPI (versions cannot be overwritten)
180+
- Network issues during upload
181+
182+
To retry, use the manual workflow dispatch method.
183+
184+
#### Version not bumped correctly
185+
186+
Ensure PRs have appropriate labels before merging. If labels are missing, the version drafter may not calculate a new version.
187+
188+
### Workflow Files Reference
189+
190+
| Workflow | Trigger | Purpose |
191+
| ------------------------------ | --------------------------- | ------------------------------------------------------------------ |
192+
| `trigger-push-stable.yml` | Push to `main`/`stable` | Calculates version, bumps `pyproject.toml`, triggers release draft |
193+
| `workflow-release-drafter.yml` | Called by push workflow | Creates/updates GitHub Release draft with notes |
194+
| `trigger-release.yml` | GitHub Release published | Triggers PyPI publish |
195+
| `workflow-publish.yml` | Release published or manual | Builds and publishes package to PyPI |

0 commit comments

Comments
 (0)