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

160

### Maturity Lifecycle

```mermaid

stateDiagram-v2

[*] --> experimental : New artifact

165

experimental --> preview : Core features complete

166

preview --> stable : Production tested

167

stable --> deprecated : Superseded or obsolete

168

deprecated --> [*] : Removed

169

```

170

171

### Contributor Guidelines

172

173

| Guideline          | Action                                                                                                                                                                                                                                                                                                                                    |

174

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

175

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

176

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

177

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

178

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

179

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

---

184

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

185

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

186

187

microsoft/hve-core

Branches

Tags

Clone

docs/contributing/release-process.md