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.

12

13

## How Releases Work

```mermaid

flowchart LR

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

18

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

19

C -->|you merge| D[GitHub Release created]

20

D --> E[Tag created on main]

21

E -.->|manual| F[Extension published]

22

```

23

24

When you merge a PR to `main`:

25

26

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

27

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

28

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

29

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

30

5. **Extension publishing** is a separate manual step

## The Release PR

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

35

36

* Updated `package.json` version

37

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

38

* Updated `CHANGELOG.md`

39

40

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.

41

42

### Version Calculation

43

44

Release-please determines the version bump from commit prefixes:

45

46

| Commit Prefix | Version Bump | Example |

47

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

48

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

49

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

50

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

51

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

52

53

## For Contributors

54

55

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

56

57

```bash

58

# Features (triggers minor version bump)

59

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

60

61

# Bug fixes (triggers patch version bump)

62

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

63

64

# Documentation (no version bump, appears in changelog)

65

git commit -m "docs: update installation guide"

66

67

# Breaking changes (triggers major version bump)

68

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

69

```

70

71

For more details, see the [commit message instructions](../../.github/instructions/hve-core/commit-message.instructions.md).

## For Maintainers

### Reviewing the Release PR

76

77

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

78

79

1. Review the accumulated changelog in the PR

80

2. Verify version bump is appropriate for the changes

81

3. Merge the Release PR

82

4. A GitHub Release is created automatically with the changelog

83

84

### Release Cadence

85

86

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

87

88

* A meaningful set of changes has accumulated

89

* A critical fix needs immediate release

90

* A scheduled release milestone is reached

91

92

There is no requirement to release after every PR merge.

93

94

## Extension Publishing

95

96

VS Code extension publishing is manual via GitHub Actions workflow dispatch.

97

98

### Publishing Steps

99

100

1. Navigate to **Actions → Publish Extension** in the repository (see [extension-publish.yml](../../.github/workflows/extension-publish.yml) for workflow details)

101

2. Select **Run workflow**

102

3. Choose the `main` branch

103

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

104

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

105

6. Click **Run workflow**

106

107

The workflow packages the extension and publishes to the VS Code Marketplace using Azure OIDC authentication.

108

109

### When to Publish

110

111

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

112

113

* New prompts, instructions, or custom agents

114

* Bug fixes affecting extension behavior

115

* Updated extension metadata or documentation

116

117

Documentation-only releases may not require an extension publish.

118

119

## Version Quick Reference

120

121

| Action | Result |

122

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

123

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

124

| Merge Release PR | GitHub Release created, tag applied |

125

| Run publish workflow | Extension published to marketplace |

126

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

127

128

## Extension Channels and Maturity

129

130

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

131

132

### Extension Channels

133

134

135

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

### Maturity Levels

140

141

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

142

143

| Level | Description | Included In |

144

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

145

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

146

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

147

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

148

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

149

150

### Maturity Lifecycle

```mermaid

stateDiagram-v2

[*] --> experimental : New artifact

155

experimental --> preview : Core features complete

156

preview --> stable : Production tested

157

stable --> deprecated : Superseded or obsolete

158

deprecated --> [*] : Removed

159

```

160

161

### Contributor Guidelines

162

163

| Guideline          | Action                                                                                                                                                                                                                                                                                                                                    |

164

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

165

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

166

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

167

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

168

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

169

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

---

174

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

175

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

176