hve-core · GitVita

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

```mermaid

flowchart LR

A[Feature PR] -->|merge| B[main branch]

19

B --> C[release-please updates Release PR]

20

C -->|you merge| D[Draft release + tag created]

21

D --> E[CI attaches assets and attestations]

22

E --> F[publish-release promotes to published]

23

F -->|automatically| G[Extension published to marketplace]

24

```

25

26

When you merge a PR to `main`:

27

28

1. **release-please analyzes commits** using conventional commit messages

29

2. **Updates the Release PR** with version bumps and changelog entries

30

3. **You decide** when to merge the Release PR

31

4. **Merging creates** a draft GitHub Release with the changelog

32

5. **CI attaches assets**, then the `publish-release` job promotes the draft to published

33

6. **Extension publishing** triggers automatically when the release is published

## The Release PR

The Release PR is not a branch cut or deployment. It is a staging mechanism containing only version metadata changes:

38

39

* Updated `package.json` version

40

* Updated `extension/templates/package.template.json` version

41

* Updated `.github/plugin/marketplace.json` (version and plugins[*].version)

42

* Updated `plugins/*/.github/plugin/plugin.json` (glob across all plugin directories)

43

* Updated `CHANGELOG.md`

44

45

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.

46

47

### Version Calculation

48

49

Release-please determines the version bump from commit prefixes:

50

51

| Commit Prefix | Version Bump | Example |

52

|--------------------------------|--------------|----------------------|

53

| `feat:` | Minor | 1.0.0 → 1.1.0 |

54

| `fix:` | Patch | 1.0.0 → 1.0.1 |

55

| `feat!:` or `BREAKING CHANGE:` | Major | 1.0.0 → 2.0.0 |

56

| `docs:`, `chore:`, `refactor:` | No bump | Grouped in changelog |

57

58

> [!NOTE]

59

> Stable releases must have an even minor version number (e.g., `1.0`, `1.2`). Odd minor versions (e.g., `1.1`, `1.3`) are reserved for pre-release or unstable versions. This convention is enforced by CI (`release-stable.yml`).

60

61

## For Contributors

62

63

Write commits using conventional commit format. This enables automated changelog generation and version bumping.

64

65

```bash

66

# Features (triggers minor version bump)

67

git commit -m "feat: add new prompt for code review"

68

69

# Bug fixes (triggers patch version bump)

70

git commit -m "fix: resolve parsing error in instruction files"

71

72

# Documentation (no version bump, appears in changelog)

73

git commit -m "docs: update installation guide"

74

75

# Breaking changes (triggers major version bump)

76

git commit -m "feat!: redesign configuration schema"

77

```

78

79

For more details, see the [commit message instructions](https://github.com/microsoft/hve-core/blob/main/.github/instructions/hve-core/commit-message.instructions.md).

## For Maintainers

### Reviewing the Release PR

84

85

The Release PR titled "chore(main): release X.Y.Z" updates automatically as PRs merge. When ready to release:

86

87

1. Review the accumulated changelog in the PR

88

2. Verify version bump is appropriate for the changes

89

3. Merge the Release PR (this creates a draft GitHub Release)

90

4. CI attaches VSIX packages, plugin ZIPs, SBOMs, and attestations to the draft release

91

5. The `publish-release` job promotes the draft to a published release

92

6. The `release: published` event triggers the marketplace publish workflow automatically

93

94

### Release Cadence

95

96

Releases are on-demand. Merge the Release PR when:

97

98

* A meaningful set of changes has accumulated

99

* A critical fix needs immediate release

100

* A scheduled release milestone is reached

101

102

There is no requirement to release after every PR merge.

103

104

## Extension Publishing

105

106

VS Code extension publishing is automated. When the `publish-release` job promotes a draft release to published, the `release: published` event triggers [`release-marketplace-stable.yml`](https://github.com/microsoft/hve-core/blob/main/.github/workflows/release-marketplace-stable.yml), which packages and publishes the extension to the VS Code Marketplace using Azure OIDC authentication.

107

108

### Manual Fallback

109

110

If the automated publish did not trigger or you need to republish, use the workflow dispatch fallback:

111

112

1. Navigate to **Actions → Stable Marketplace Publish** in the repository

113

2. Select **Run workflow**

114

3. Choose the `main` branch

115

4. Optionally specify a version (defaults to `package.json` version)

116

5. Optionally enable dry-run mode to package without publishing

117

6. Click **Run workflow**

118

119

### When to Publish

120

121

Publish the extension after merging a Release PR that includes extension-relevant changes:

122

123

* New prompts, instructions, or custom agents

124

* Bug fixes affecting extension behavior

125

* Updated extension metadata or documentation

126

127

Documentation-only releases may not require an extension publish.

128

129

## Version Quick Reference

130

131

| Action | Result |

132

|--------------------------|---------------------------------------------------------------|

133

| Merge feature PR to main | Release PR updates with new changelog entry |

134

| Merge Release PR | Draft GitHub Release created, then auto-promoted to published |

135

| Release published | Extension automatically published to marketplace |

136

| Merge docs-only PR | Changelog updated, no version bump |

137

138

## Extension Channels and Maturity

139

140

The VS Code extension is published to two channels with different stability expectations.

141

142

### Extension Channels

143

144

145

|-------------|------------------|-------------------------------------|----------------|

### Maturity Levels

150

151

Each prompt, instruction, agent, and skill can set `maturity` in `collections/*.collection.yml` under `items[]`:

152

153

| Level          | Description                                                                                       | Included In         |

154

|----------------|---------------------------------------------------------------------------------------------------|---------------------|

155

| `stable`       | Production-ready, fully tested                                                                    | Stable, Pre-release |

156

| `preview`      | Feature-complete but may have rough edges                                                         | Pre-release only    |

157

| `experimental` | Early development, may change significantly                                                       | Pre-release only    |

158

| `deprecated`   | Scheduled for removal, excluded from all builds                                                   | Neither             |

159

| `removed`      | Source retained for traceability; excluded from all generated plugins and extension distributions | Neither             |

160

161

### Maturity Lifecycle

```mermaid

stateDiagram-v2

[*] --> experimental : New artifact

166

experimental --> preview : Core features complete

167

preview --> stable : Production tested

168

stable --> deprecated : Superseded or obsolete

169

deprecated --> removed : Withdrawn from distribution

170

removed --> [*] : Source eventually deleted

171

```

172

173

The `removed` level is a collection-YAML-only marker. The artifact file remains in its

174

source location (for example, under `.github/skills/{collection-id}/`) so history and

175

references stay intact, but every downstream surface (collection validation, plugin

176

generation, and extension packaging) excludes it. Use `removed` when you want to retire

177

an artifact from distribution without moving it to `.github/deprecated/` or deleting it

178

outright. See [AI Artifacts Architecture - Removed Artifacts](../architecture/ai-artifacts.md#removed-artifacts)

179

for the architectural contract.

180

181

### Contributor Guidelines

182

183

| Guideline          | Action                                                                                                                                                                                                                                                                                                                                                                                                                           |

184

|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

185

| New contributions  | Set `stable` on collection items unless explicitly targeting early adopters                                                                                                                                                                                                                                                                                                                                                      |

186

| Experimental work  | Set `experimental` on collection items for proof-of-concept or rapidly evolving artifacts                                                                                                                                                                                                                                                                                                                                        |

187

| Preview promotions | Set `preview` on collection items when core functionality is complete                                                                                                                                                                                                                                                                                                                                                            |

188

| Stable promotions  | Set `stable` on collection items after production validation                                                                                                                                                                                                                                                                                                                                                                     |

189

| 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.                                                                                        |

190

| Removal            | Set `removed` on collection items when the artifact should no longer ship in any plugin or extension build but its source should remain in place for history, references, or future reinstatement. The collection YAML is the single source of truth - no per-artifact frontmatter or file move is required. See [AI Artifacts Architecture - Removed Artifacts](../architecture/ai-artifacts.md#removed-artifacts) for details. |

---

195

*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,

196

then carefully refined by our team of discerning human reviewers.*

197

198

microsoft/hve-core

Branches

Tags

Clone

docs/contributing/release-process.md