microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/contributing/release-process.md
177lines · modecode
| 1 | --- |
| 2 | title: Release Process |
| 3 | description: Trunk-based release workflow using release-please automation and manual VS Code extension publishing |
| 4 | sidebar_position: 9 |
| 5 | ms.date: 2026-01-08 |
| 6 | ms.topic: how-to |
| 7 | author: WilliamBerryiii |
| 8 | --- |
| 9 | |
| 10 | ## Overview |
| 11 | |
| 12 | This project uses trunk-based development with automated release management. All changes go directly to `main` via pull requests, and [release-please](https://github.com/googleapis/release-please) handles version bumping, changelog generation, and GitHub releases automatically. |
| 13 | |
| 14 | ## How Releases Work |
| 15 | |
| 16 | ```mermaid |
| 17 | flowchart LR |
| 18 | A[Feature PR] -->|merge| B[main branch] |
| 19 | B --> C[release-please updates Release PR] |
| 20 | C -->|you merge| D[GitHub Release created] |
| 21 | D --> E[Tag created on main] |
| 22 | E -.->|manual| F[Extension published] |
| 23 | ``` |
| 24 | |
| 25 | When you merge a PR to `main`: |
| 26 | |
| 27 | 1. **release-please analyzes commits** using conventional commit messages |
| 28 | 2. **Updates the Release PR** with version bumps and changelog entries |
| 29 | 3. **You decide** when to merge the Release PR |
| 30 | 4. **Merging creates** a GitHub Release with the changelog |
| 31 | 5. **Extension publishing** is a separate manual step |
| 32 | |
| 33 | ## The Release PR |
| 34 | |
| 35 | The Release PR is not a branch cut or deployment. It is a staging mechanism containing only version metadata changes: |
| 36 | |
| 37 | * Updated `package.json` version |
| 38 | * Updated `extension/templates/package.template.json` version |
| 39 | * Updated `CHANGELOG.md` |
| 40 | |
| 41 | Your actual code changes are already on `main` from your feature PRs. The Release PR accumulates version and changelog updates until you are ready to release. |
| 42 | |
| 43 | ### Version Calculation |
| 44 | |
| 45 | Release-please determines the version bump from commit prefixes: |
| 46 | |
| 47 | | Commit Prefix | Version Bump | Example | |
| 48 | |--------------------------------|--------------|----------------------| |
| 49 | | `feat:` | Minor | 1.0.0 → 1.1.0 | |
| 50 | | `fix:` | Patch | 1.0.0 → 1.0.1 | |
| 51 | | `feat!:` or `BREAKING CHANGE:` | Major | 1.0.0 → 2.0.0 | |
| 52 | | `docs:`, `chore:`, `refactor:` | No bump | Grouped in changelog | |
| 53 | |
| 54 | ## For Contributors |
| 55 | |
| 56 | Write commits using conventional commit format. This enables automated changelog generation and version bumping. |
| 57 | |
| 58 | ```bash |
| 59 | # Features (triggers minor version bump) |
| 60 | git commit -m "feat: add new prompt for code review" |
| 61 | |
| 62 | # Bug fixes (triggers patch version bump) |
| 63 | git commit -m "fix: resolve parsing error in instruction files" |
| 64 | |
| 65 | # Documentation (no version bump, appears in changelog) |
| 66 | git commit -m "docs: update installation guide" |
| 67 | |
| 68 | # Breaking changes (triggers major version bump) |
| 69 | git commit -m "feat!: redesign configuration schema" |
| 70 | ``` |
| 71 | |
| 72 | For more details, see the [commit message instructions](https://github.com/microsoft/hve-core/blob/main/.github/instructions/hve-core/commit-message.instructions.md). |
| 73 | |
| 74 | ## For Maintainers |
| 75 | |
| 76 | ### Reviewing the Release PR |
| 77 | |
| 78 | The Release PR titled "chore(main): release X.Y.Z" updates automatically as PRs merge. When ready to release: |
| 79 | |
| 80 | 1. Review the accumulated changelog in the PR |
| 81 | 2. Verify version bump is appropriate for the changes |
| 82 | 3. Merge the Release PR |
| 83 | 4. A GitHub Release is created automatically with the changelog |
| 84 | |
| 85 | ### Release Cadence |
| 86 | |
| 87 | Releases are on-demand. Merge the Release PR when: |
| 88 | |
| 89 | * A meaningful set of changes has accumulated |
| 90 | * A critical fix needs immediate release |
| 91 | * A scheduled release milestone is reached |
| 92 | |
| 93 | There is no requirement to release after every PR merge. |
| 94 | |
| 95 | ## Extension Publishing |
| 96 | |
| 97 | VS Code extension publishing is manual via GitHub Actions workflow dispatch. |
| 98 | |
| 99 | ### Publishing Steps |
| 100 | |
| 101 | 1. Navigate to **Actions → Stable Marketplace Publish** in the repository (see [release-marketplace-stable.yml](https://github.com/microsoft/hve-core/blob/main/.github/workflows/release-marketplace-stable.yml) for workflow details) |
| 102 | 2. Select **Run workflow** |
| 103 | 3. Choose the `main` branch |
| 104 | 4. Optionally specify a version (defaults to `package.json` version) |
| 105 | 5. Optionally enable dry-run mode to package without publishing |
| 106 | 6. Click **Run workflow** |
| 107 | |
| 108 | The workflow packages the extension and publishes to the VS Code Marketplace using Azure OIDC authentication. |
| 109 | |
| 110 | ### When to Publish |
| 111 | |
| 112 | Publish the extension after merging a Release PR that includes extension-relevant changes: |
| 113 | |
| 114 | * New prompts, instructions, or custom agents |
| 115 | * Bug fixes affecting extension behavior |
| 116 | * Updated extension metadata or documentation |
| 117 | |
| 118 | Documentation-only releases may not require an extension publish. |
| 119 | |
| 120 | ## Version Quick Reference |
| 121 | |
| 122 | | Action | Result | |
| 123 | |--------------------------|---------------------------------------------| |
| 124 | | Merge feature PR to main | Release PR updates with new changelog entry | |
| 125 | | Merge Release PR | GitHub Release created, tag applied | |
| 126 | | Run publish workflow | Extension published to marketplace | |
| 127 | | Merge docs-only PR | Changelog updated, no version bump | |
| 128 | |
| 129 | ## Extension Channels and Maturity |
| 130 | |
| 131 | The VS Code extension is published to two channels with different stability expectations. |
| 132 | |
| 133 | ### Extension Channels |
| 134 | |
| 135 | | Channel | Stability | Included Maturity Levels | Audience | |
| 136 | |-------------|------------------|-------------------------------------|----------------| |
| 137 | | Stable | Production-ready | `stable` only | All users | |
| 138 | | Pre-release | Early access | `stable`, `preview`, `experimental` | Early adopters | |
| 139 | |
| 140 | ### Maturity Levels |
| 141 | |
| 142 | Each prompt, instruction, agent, and skill can set `maturity` in `collections/*.collection.yml` under `items[]`: |
| 143 | |
| 144 | | Level | Description | Included In | |
| 145 | |----------------|-------------------------------------------------|---------------------| |
| 146 | | `stable` | Production-ready, fully tested | Stable, Pre-release | |
| 147 | | `preview` | Feature-complete but may have rough edges | Pre-release only | |
| 148 | | `experimental` | Early development, may change significantly | Pre-release only | |
| 149 | | `deprecated` | Scheduled for removal, excluded from all builds | Neither | |
| 150 | |
| 151 | ### Maturity Lifecycle |
| 152 | |
| 153 | ```mermaid |
| 154 | stateDiagram-v2 |
| 155 | [*] --> experimental : New artifact |
| 156 | experimental --> preview : Core features complete |
| 157 | preview --> stable : Production tested |
| 158 | stable --> deprecated : Superseded or obsolete |
| 159 | deprecated --> [*] : Removed |
| 160 | ``` |
| 161 | |
| 162 | ### Contributor Guidelines |
| 163 | |
| 164 | | Guideline | Action | |
| 165 | |--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| 166 | | New contributions | Set `stable` on collection items unless explicitly targeting early adopters | |
| 167 | | Experimental work | Set `experimental` on collection items for proof-of-concept or rapidly evolving artifacts | |
| 168 | | Preview promotions | Set `preview` on collection items when core functionality is complete | |
| 169 | | Stable promotions | Set `stable` on collection items after production validation | |
| 170 | | Deprecation | Set `deprecated` on collection items before removal to provide transition time. Move the artifact file to `.github/deprecated/{type}/` so the build system excludes it from all downstream surfaces automatically. See [AI Artifacts Architecture](../architecture/ai-artifacts.md#deprecated-artifacts) for the full deprecation policy. | |
| 171 | |
| 172 | --- |
| 173 | |
| 174 | <!-- markdownlint-disable MD036 --> |
| 175 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 176 | then carefully refined by our team of discerning human reviewers.* |
| 177 | <!-- markdownlint-enable MD036 --> |
| 178 | |