Skip to content

Commit 649a682

Browse files
committed
docs: [#448] update issue spec with completed tasks and fix step order
1 parent fc87174 commit 649a682

1 file changed

Lines changed: 57 additions & 54 deletions

File tree

docs/issues/448-release-process-branch-tag-docker-crate.md

Lines changed: 57 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -25,20 +25,20 @@ The initial release process should include these mandatory steps in order:
2525
3. Push the release commit to `main`
2626
4. Create the release tag and push it
2727
5. Create the release branch and push it
28-
6. Create the GitHub release from the tag
29-
7. Let GitHub Actions publish release artifacts:
28+
6. Let GitHub Actions publish release artifacts:
3029
- Docker image for the release branch
3130
- Crate for the release branch
31+
7. Create the GitHub release from the tag
3232

3333
## Goals
3434

35-
- [ ] Define a single documented release workflow with explicit step order
36-
- [ ] Make branch and tag conventions consistent across releases
37-
- [ ] Ensure Docker image publication is triggered from release branches
38-
- [ ] Ensure crate publication is triggered from release branches
39-
- [ ] Define validation and rollback guidance for failed release steps
40-
- [ ] Keep the first version of the process intentionally simpler than the tracker repository
41-
- [ ] Avoid duplicate Docker release tags for the same version
35+
- [x] Define a single documented release workflow with explicit step order
36+
- [x] Make branch and tag conventions consistent across releases
37+
- [x] Ensure Docker image publication is triggered from release branches
38+
- [x] Ensure crate publication is triggered from release branches
39+
- [x] Define validation and rollback guidance for failed release steps
40+
- [x] Keep the first version of the process intentionally simpler than the tracker repository
41+
- [x] Avoid duplicate Docker release tags for the same version
4242

4343
## 🏗️ Architecture Requirements
4444

@@ -48,21 +48,21 @@ The initial release process should include these mandatory steps in order:
4848

4949
### Module Structure Requirements
5050

51-
- [ ] Keep process documentation in `docs/`
52-
- [ ] Keep automation in `.github/workflows/` and/or `scripts/`
53-
- [ ] Keep branch and tag naming rules explicit and testable
54-
- [ ] Keep artifact version alignment across Git tag, Docker image tag, and crate version
51+
- [x] Keep process documentation in `docs/`
52+
- [x] Keep automation in `.github/workflows/` and/or `scripts/`
53+
- [x] Keep branch and tag naming rules explicit and testable
54+
- [x] Keep artifact version alignment across Git tag, Docker image tag, and crate version
5555

5656
### Architectural Constraints
5757

58-
- [ ] Release order must be deterministic and documented
59-
- [ ] Tag format must be clearly defined as `vX.Y.Z`
60-
- [ ] Release branch format must be clearly defined and compatible with workflow triggers
61-
- [ ] Docker publish step must support reproducible release tagging without overloading `main` publish behavior
62-
- [ ] Docker release tags must not include the Git tag `v` prefix
63-
- [ ] Crate publish step must define pre-checks and ownership requirements
64-
- [ ] Docker Hub credentials must separate secrets from non-sensitive variables
65-
- [ ] Workflow triggers and branch protections must align with allowed branches (`develop`, `main`, `releases/**/*`)
58+
- [x] Release order must be deterministic and documented
59+
- [x] Tag format must be clearly defined as `vX.Y.Z`
60+
- [x] Release branch format must be clearly defined and compatible with workflow triggers
61+
- [x] Docker publish step must support reproducible release tagging without overloading `main` publish behavior
62+
- [x] Docker release tags must not include the Git tag `v` prefix
63+
- [x] Crate publish step must define pre-checks and ownership requirements
64+
- [x] Docker Hub credentials must separate secrets from non-sensitive variables
65+
- [x] Workflow triggers and branch protections must align with allowed branches (`develop`, `main`, `releases/**/*`)
6666

6767
### Anti-Patterns to Avoid
6868

@@ -224,59 +224,62 @@ Define repository settings expectations that release automation depends on.
224224

225225
### Phase 1: Define the Manual Release Sequence (estimated time: 2-3 hours)
226226

227-
- [ ] Task 1.1: Document the simplified release steps from version bump through GitHub release creation
228-
- [ ] Task 1.2: Define version, tag, and release branch naming conventions
229-
- [ ] Task 1.3: Specify which `Cargo.toml` files must be updated for each release
230-
- [ ] Task 1.4: Add a pre-flight checklist for environments, permissions, and clean git state
227+
- [x] Task 1.1: Document the simplified release steps from version bump through GitHub release creation
228+
- [x] Task 1.2: Define version, tag, and release branch naming conventions
229+
- [x] Task 1.3: Specify which `Cargo.toml` files must be updated for each release
230+
- [x] Task 1.4: Add a pre-flight checklist for environments, permissions, and clean git state
231231

232232
### Phase 2: Docker Release Branch Publishing (estimated time: 1-2 hours)
233233

234-
- [ ] Task 2.1: Extend `container.yaml` to trigger on `releases/**/*`
235-
- [ ] Task 2.2: Add release branch context detection and release image tags
236-
- [ ] Task 2.3: Define image verification, credential, and rerun requirements
237-
- [ ] Task 2.4: Ensure Docker Hub username/repository are configured as non-secret variables (token remains secret)
234+
- [x] Task 2.1: Extend `container.yaml` to trigger on `releases/**/*`
235+
- [x] Task 2.2: Add release branch context detection and release image tags
236+
- [x] Task 2.3: Define image verification, credential, and rerun requirements
237+
- [x] Task 2.4: Ensure Docker Hub username/repository are configured as non-secret variables (token remains secret)
238238

239239
### Phase 3: Crate Publishing Workflow (estimated time: 1-2 hours)
240240

241-
- [ ] Task 3.1: Create a dedicated workflow for publishing the SDK crate from `releases/**/*`
242-
- [ ] Task 3.2: Define package inspection, dry-run, publish, and post-publish verification steps
243-
- [ ] Task 3.3: Define dedicated environment and document cargo registry credentials and failure recovery rules
244-
- [ ] Task 3.4: Add docs.rs post-publish verification guidance
241+
- [x] Task 3.1: Create a dedicated workflow for publishing the SDK crate from `releases/**/*`
242+
- [x] Task 3.2: Define package inspection, dry-run, publish, and post-publish verification steps
243+
- [x] Task 3.3: Define dedicated environment and document cargo registry credentials and failure recovery rules
244+
- [x] Task 3.4: Add docs.rs post-publish verification guidance
245245

246246
### Phase 4: Validation and Operational Guidance (estimated time: 2-4 hours)
247247

248248
- [ ] Task 4.1: Validate the end-to-end release flow against a test version
249-
- [ ] Task 4.2: Document how maintainers verify Docker image, crate publication, and GitHub release creation
250-
- [ ] Task 4.3: Add troubleshooting notes for partial publication failures
251-
- [ ] Task 4.4: Add explicit idempotency/re-run guidance and crate yank policy
249+
- [x] Task 4.2: Document how maintainers verify Docker image, crate publication, and GitHub release creation
250+
- [x] Task 4.3: Add troubleshooting notes for partial publication failures
251+
- [x] Task 4.4: Add explicit idempotency/re-run guidance and crate yank policy
252+
253+
> Note: The practical end-to-end validation for Task 4.1 is planned as the
254+
> post-merge `0.1.0-beta` release run.
252255
253256
## Acceptance Criteria
254257

255258
> **Note for Contributors**: These criteria define what the PR reviewer will check. Use this as your pre-review checklist before submitting the PR to minimize back-and-forth iterations.
256259
257260
**Quality Checks**:
258261

259-
- [ ] Pre-commit checks pass: `./scripts/pre-commit.sh`
262+
- [x] Pre-commit checks pass: `./scripts/pre-commit.sh`
260263

261264
**Task-Specific Criteria**:
262265

263-
- [ ] The documented release process follows this order: version update, release commit, push to `main`, tag push, release branch push, GitHub release creation, workflow-driven artifact publication
264-
- [ ] The spec defines explicit finalization gates (main push, tag push, release branch push, Docker pass, crate pass, GitHub release)
265-
- [ ] Branch naming and tag naming conventions are documented as `releases/vX.Y.Z` and `vX.Y.Z`
266-
- [ ] `container.yaml` is specified to publish Docker images for release branches in addition to existing `main` and `develop` behavior
267-
- [ ] The spec explicitly requires Docker release tags to use `X.Y.Z` and forbids `vX.Y.Z` image tags
268-
- [ ] A separate crate publication workflow is specified for the SDK crate on `releases/**/*`
269-
- [ ] The spec explicitly records the decision to keep Docker and crate publication in independent workflows
270-
- [ ] Docker Hub configuration policy is explicit: token is secret, username/repository are variables
271-
- [ ] Release workflow branch scope is explicit and aligned with `develop`, `main`, and `releases/**/*`
272-
- [ ] Docker publish procedure includes verification and failure handling
273-
- [ ] Crate publish procedure includes dry-run and post-publish verification
274-
- [ ] Crate publish procedure includes package content inspection before publish
275-
- [ ] Crate publish procedure includes docs.rs build verification after publish
276-
- [ ] Pre-flight checks are documented for environments, secrets/variables, permissions, and git state
277-
- [ ] Partial-failure and re-run rules are documented for Docker and crate workflows
278-
- [ ] Crate rollback policy includes explicit yank criteria and patch-release follow-up
279-
- [ ] Version consistency rules are documented across Git tags, Docker tags, and crate versions
266+
- [x] The documented release process follows this order: version update, release commit, push to `main`, tag push, release branch push, workflow-driven artifact publication, GitHub release creation
267+
- [x] The spec defines explicit finalization gates (main push, tag push, release branch push, Docker pass, crate pass, GitHub release)
268+
- [x] Branch naming and tag naming conventions are documented as `releases/vX.Y.Z` and `vX.Y.Z`
269+
- [x] `container.yaml` is specified to publish Docker images for release branches in addition to existing `main` and `develop` behavior
270+
- [x] The spec explicitly requires Docker release tags to use `X.Y.Z` and forbids `vX.Y.Z` image tags
271+
- [x] A separate crate publication workflow is specified for the SDK crate on `releases/**/*`
272+
- [x] The spec explicitly records the decision to keep Docker and crate publication in independent workflows
273+
- [x] Docker Hub configuration policy is explicit: token is secret, username/repository are variables
274+
- [x] Release workflow branch scope is explicit and aligned with `develop`, `main`, and `releases/**/*`
275+
- [x] Docker publish procedure includes verification and failure handling
276+
- [x] Crate publish procedure includes dry-run and post-publish verification
277+
- [x] Crate publish procedure includes package content inspection before publish
278+
- [x] Crate publish procedure includes docs.rs build verification after publish
279+
- [x] Pre-flight checks are documented for environments, secrets/variables, permissions, and git state
280+
- [x] Partial-failure and re-run rules are documented for Docker and crate workflows
281+
- [x] Crate rollback policy includes explicit yank criteria and patch-release follow-up
282+
- [x] Version consistency rules are documented across Git tags, Docker tags, and crate versions
280283

281284
## Related Documentation
282285

0 commit comments

Comments
 (0)