Skip to content

Commit e4d1cde

Browse files
elasticdotventureselasticdotventures
committed
chore: update README
1 parent 70a96b8 commit e4d1cde

File tree

3 files changed

+339
-3
lines changed

3 files changed

+339
-3
lines changed

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,6 @@ This project is licensed under the MIT License. See the [LICENSE](LICENSE) file
9898

9999
**Syntax Highlighting**: Syntax highlighting and language configuration features were adapted from the [wolfmah-vscode.just-syntax](https://github.com/wolfmah-vscode/just-syntax) repository under the Mozilla Public License 2.0 (MPL 2.0). See the [LICENSE](LICENSE) file for details.
100100

101-
## Thanks
102-
* skellock
103-
*
101+
## Additional Thanks
102+
* Robert Neff - nefrob.vscode-just-syntax
103+
* skellock - skellock.just

‎RELEASE.md‎

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
# Release Process
2+
3+
This document provides comprehensive instructions for the automated release process of the just-vscode-extension. The project uses modern tooling for conventional commits, automated versioning, and continuous delivery.
4+
5+
## Overview
6+
7+
The release system is built around:
8+
- **Conventional Commits** for semantic versioning
9+
- **Semantic Release** for automated version management
10+
- **GitHub Actions** for continuous deployment
11+
- **VSCode Marketplace** and **Open VSX** publishing
12+
13+
## Toolchain
14+
15+
### Core Tools
16+
- **[Commitizen](https://commitizen-tools.github.io/commitizen/)**: Interactive commit creation
17+
- **[Commitlint](https://commitlint.js.org/)**: Commit message validation
18+
- **[Husky](https://typicode.github.io/husky/)**: Git hooks automation
19+
- **[Semantic Release](https://semantic-release.gitbook.io/)**: Automated versioning and publishing
20+
- **[semantic-release-vsce](https://github.com/felipecrs/semantic-release-vsce)**: VSCode extension publishing plugin
21+
22+
### Configuration Files
23+
- `commitlint.config.js` - Commit message rules
24+
- `.releaserc.json` - Semantic release configuration
25+
- `.github/workflows/release.yml` - GitHub Actions workflow
26+
- `.husky/commit-msg` - Commit validation hook
27+
- `.husky/pre-commit` - Pre-commit type checking and linting
28+
29+
## Conventional Commits
30+
31+
All commits must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
32+
33+
```
34+
<type>[optional scope]: <description>
35+
36+
[optional body]
37+
38+
[optional footer(s)]
39+
```
40+
41+
### Commit Types
42+
43+
| Type | Description | Version Impact |
44+
|------|-------------|----------------|
45+
| `feat` | New features | Minor (0.x.0) |
46+
| `fix` | Bug fixes | Patch (0.0.x) |
47+
| `docs` | Documentation changes | None |
48+
| `style` | Code style changes | None |
49+
| `refactor` | Code refactoring | None |
50+
| `perf` | Performance improvements | Patch (0.0.x) |
51+
| `test` | Test changes | None |
52+
| `build` | Build system changes | None |
53+
| `ci` | CI/CD changes | None |
54+
| `chore` | Maintenance tasks | None |
55+
| `revert` | Revert previous commit | Depends on reverted commit |
56+
57+
### Breaking Changes
58+
Add `BREAKING CHANGE:` in the commit footer to trigger a major version bump (x.0.0).
59+
60+
```
61+
feat: add new configuration option
62+
63+
BREAKING CHANGE: Configuration format has changed, requires manual migration
64+
```
65+
66+
## Making Commits
67+
68+
### Method 1: Interactive Commitizen (Recommended)
69+
```bash
70+
# Stage your changes
71+
git add .
72+
73+
# Use interactive commit creation
74+
pnpm run commit
75+
```
76+
77+
This will guide you through:
78+
1. Selecting commit type
79+
2. Entering scope (optional)
80+
3. Writing description
81+
4. Adding body (optional)
82+
5. Noting breaking changes
83+
6. Referencing issues
84+
85+
### Method 2: Manual Commits
86+
```bash
87+
# Follow conventional commit format
88+
git commit -m "feat(parser): add support for nested expressions"
89+
git commit -m "fix: resolve memory leak in watcher"
90+
git commit -m "docs: update installation instructions"
91+
```
92+
93+
### Validation
94+
All commits are automatically validated by:
95+
- **Pre-commit hook**: Runs type checking and linting
96+
- **Commit-msg hook**: Validates commit message format
97+
98+
## Release Workflow
99+
100+
### 1. Development Phase
101+
- Work on feature branches (`feature/`, `fix/`, `docs/`, etc.)
102+
- Use conventional commits for all changes
103+
- Create pull requests to `main` branch
104+
105+
### 2. Pull Request Process
106+
- PR title should follow conventional commit format
107+
- All checks must pass (linting, type checking)
108+
- Code review required
109+
- Squash and merge with conventional commit message
110+
111+
### 3. Automated Release
112+
When merged to `main` branch, GitHub Actions automatically:
113+
114+
1. **Analyzes commits** since last release
115+
2. **Determines version bump** based on commit types
116+
3. **Generates changelog** from commit messages
117+
4. **Updates package.json** version
118+
5. **Creates GitHub release** with release notes
119+
6. **Publishes to VSCode Marketplace**
120+
7. **Publishes to Open VSX Registry**
121+
8. **Commits changes** back to repository
122+
123+
### 4. Release Artifacts
124+
- **GitHub Release**: Tagged release with generated notes
125+
- **VSIX Package**: Built extension package
126+
- **Marketplace Listing**: Updated VSCode Marketplace entry
127+
- **Open VSX Listing**: Updated Open VSX Registry entry
128+
129+
## Manual Release Process
130+
131+
### Dry Run Testing
132+
```bash
133+
# Test release process without publishing
134+
npx semantic-release --dry-run
135+
```
136+
137+
### Emergency Manual Release
138+
```bash
139+
# Only use in emergencies when automation fails
140+
pnpm run release
141+
```
142+
143+
## GitHub Repository Configuration
144+
145+
### Required Secrets
146+
Configure these in GitHub repository settings > Secrets and variables > Actions:
147+
148+
| Secret | Description | Required For |
149+
|--------|-------------|--------------|
150+
| `VSCE_PAT` | VSCode Marketplace Personal Access Token | Marketplace publishing |
151+
| `OVSX_PAT` | Open VSX Registry Personal Access Token | Open VSX publishing |
152+
153+
### Personal Access Token Setup
154+
155+
#### VSCode Marketplace Token
156+
1. Visit [Visual Studio Marketplace Publisher Management](https://marketplace.visualstudio.com/manage)
157+
2. Create new Personal Access Token
158+
3. Scope: **All accessible organizations**
159+
4. Expiration: Set appropriate duration
160+
5. Add to GitHub secrets as `VSCE_PAT`
161+
162+
#### Open VSX Token
163+
1. Visit [Open VSX Registry](https://open-vsx.org/)
164+
2. Sign in and go to user settings
165+
3. Generate new Access Token
166+
4. Add to GitHub secrets as `OVSX_PAT`
167+
168+
## Version Management
169+
170+
### Automatic Versioning
171+
- **Never manually update** `package.json` version
172+
- Versions are determined by commit analysis
173+
- Follows [Semantic Versioning](https://semver.org/) strictly
174+
175+
### Version Calculation Examples
176+
```bash
177+
# Current version: 1.2.3
178+
179+
# feat: new feature → 1.3.0 (minor bump)
180+
# fix: bug fix → 1.2.4 (patch bump)
181+
# feat: BREAKING CHANGE → 2.0.0 (major bump)
182+
# docs: update readme → 1.2.3 (no bump)
183+
```
184+
185+
### Pre-release Versions
186+
For beta releases, create a `beta` branch:
187+
```bash
188+
git checkout -b beta
189+
# Make changes and commit
190+
git push origin beta
191+
```
192+
193+
Semantic release will create pre-release versions like `1.3.0-beta.1`.
194+
195+
## Changelog Management
196+
197+
### Automatic Generation
198+
- `CHANGELOG.md` is automatically updated
199+
- Generated from conventional commit messages
200+
- Includes links to commits and GitHub issues
201+
- Follows [Keep a Changelog](https://keepachangelog.com/) format
202+
203+
### Manual Changelog Edits
204+
If needed, edit `CHANGELOG.md` manually, then commit:
205+
```bash
206+
git add CHANGELOG.md
207+
git commit -m "docs: update changelog with additional context"
208+
```
209+
210+
## Troubleshooting
211+
212+
### Common Issues
213+
214+
#### 1. Commit Validation Fails
215+
```bash
216+
# Error: subject may not be empty [subject-empty]
217+
# Solution: Follow conventional commit format
218+
git commit -m "feat: add new feature description"
219+
```
220+
221+
#### 2. Pre-commit Hook Fails
222+
```bash
223+
# Error: TypeScript errors or linting issues
224+
# Solution: Fix issues before committing
225+
pnpm run check-types
226+
pnpm run lint
227+
```
228+
229+
#### 3. Release Workflow Fails
230+
- Check GitHub Actions logs
231+
- Verify secrets are configured
232+
- Ensure main branch protection rules allow semantic-release bot
233+
234+
#### 4. Marketplace Publishing Fails
235+
- Verify `VSCE_PAT` token is valid and has correct permissions
236+
- Check extension manifest validity
237+
- Ensure version number is higher than published version
238+
239+
### Getting Help
240+
- Check [Semantic Release Documentation](https://semantic-release.gitbook.io/)
241+
- Review [Conventional Commits Specification](https://www.conventionalcommits.org/)
242+
- Check GitHub Actions workflow logs for detailed error messages
243+
244+
## Development Scripts
245+
246+
| Command | Description |
247+
|---------|-------------|
248+
| `pnpm run commit` | Interactive conventional commit |
249+
| `pnpm run release` | Manual semantic release |
250+
| `pnpm run check-types` | TypeScript type checking |
251+
| `pnpm run lint` | ESLint code linting |
252+
| `pnpm run package` | Build production extension |
253+
| `npx semantic-release --dry-run` | Test release without publishing |
254+
| `echo "feat: test" \| npx commitlint` | Test commit message validation |
255+
256+
## Release Checklist
257+
258+
Before major releases, verify:
259+
260+
- [ ] All tests pass locally
261+
- [ ] Documentation is up to date
262+
- [ ] Breaking changes are documented
263+
- [ ] GitHub secrets are configured
264+
- [ ] Extension manifest is valid
265+
- [ ] Version dependencies are compatible
266+
267+
## Best Practices
268+
269+
1. **Use descriptive commit messages** that explain the "why" not just the "what"
270+
2. **Group related changes** into single commits when possible
271+
3. **Reference issues** in commit messages using `closes #123` syntax
272+
4. **Test thoroughly** before merging to main branch
273+
5. **Keep commits atomic** - one logical change per commit
274+
6. **Use conventional scopes** consistently (e.g., `feat(parser):`, `fix(ui):`)
275+
276+
## Release History
277+
278+
All releases are tracked in:
279+
- [GitHub Releases](https://github.com/elasticdotventures/just-vscode-extension/releases)
280+
- [CHANGELOG.md](./CHANGELOG.md)
281+
- [VSCode Marketplace History](https://marketplace.visualstudio.com/items?itemName=promptexecution.justlang-lsp)

‎TODO.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
> what needs to happen for me to publish this into the vscode marketplace?
2+
3+
● To publish to the VSCode Marketplace, you need:
4+
5+
1. VSCode Marketplace Publisher Account
6+
7+
- Create account at https://marketplace.visualstudio.com/manage
8+
- Set up publisher profile (this becomes your extension namespace)
9+
10+
2. Personal Access Token (PAT)
11+
12+
- In your publisher dashboard, create a Personal Access Token
13+
- Scope: All accessible organizations
14+
- Add as GitHub secret: VSCE_PAT
15+
16+
3. Extension Manifest Updates
17+
18+
Your package.json needs:
19+
{
20+
"publisher": "your-publisher-name", // Currently "promptexecution"
21+
"name": "just-vscode-extension", // Extension ID
22+
"displayName": "Just VSCode Extension" // Marketplace display name
23+
}
24+
25+
4. GitHub Secrets Configuration
26+
27+
In your GitHub repo settings > Secrets and variables > Actions:
28+
- VSCE_PAT: Your VSCode Marketplace token
29+
- OVSX_PAT: Open VSX token (optional but recommended)
30+
31+
5. Merge to Main Branch
32+
33+
Once configured, any merge to main with conventional commits will:
34+
- Auto-bump version based on commit types
35+
- Build the extension
36+
- Publish to marketplace
37+
- Create GitHub release
38+
39+
Current Status Check
40+
41+
Looking at your package.json:3, your publisher is already set to "promptexecution". You'll need:
42+
43+
1. Verify publisher exists in VSCode Marketplace
44+
2. Create PAT and add to GitHub secrets
45+
3. Test with dry run: npx semantic-release --dry-run
46+
4. Merge to main to trigger first automated release
47+
48+
The automation is already set up - you just need the marketplace credentials!
49+
50+
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
51+
│ >  │
52+
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
53+
? for shortcuts
54+
55+

0 commit comments

Comments
 (0)