Skip to content

Commit ef68308

Browse files
JayNightmareJayNightmare
committed
Enhances release workflow with detailed notes and usage guide
Updates the release workflow to generate comprehensive release notes, including a changelog, setup instructions, and troubleshooting guide. Improves clarity for users and addresses common issues with installation and usage. Removes optional steps and simplifies secrets setup by documenting required secrets. Refines release creation process to ensure better user experience with draft releases. Fixes potential errors related to dependency configuration and streamlines instructions for local testing.
1 parent 68233d9 commit ef68308

File tree

2 files changed

+151
-64
lines changed

2 files changed

+151
-64
lines changed

‎.github/workflows/README.md‎

Lines changed: 27 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -12,18 +12,21 @@ This directory contains GitHub Actions workflows for the DisTrack VS Code Extens
1212
- Installs dependencies with `npm ci`
1313
- Runs ESLint for code quality
1414
- Compiles TypeScript code
15-
- Runs tests
1615
- Builds the extension
1716
- Uploads build artifacts
18-
- Performs security audits
17+
- Performs security audits (high level only)
1918

2019
### 🏷️ Release (`release.yml`)
2120
**Triggers:** Push of version tags (e.g., `v1.0.0`)
2221
**Purpose:** Automated release creation and VSIX packaging
2322

2423
- Builds and tests the extension
2524
- Creates a VSIX package
26-
- Generates a GitHub release with release notes
25+
- Generates comprehensive release notes including:
26+
- Full changelog from CHANGELOG.md
27+
- Detailed usage instructions
28+
- Troubleshooting guide for common errors
29+
- Creates a draft GitHub release with release notes
2730
- Uploads VSIX file as release asset
2831
- Stores build artifacts
2932

@@ -43,7 +46,6 @@ This directory contains GitHub Actions workflows for the DisTrack VS Code Extens
4346
- Checks code formatting with Prettier
4447
- Runs ESLint
4548
- Performs TypeScript type checking
46-
- Runs tests
4749
- Builds the extension
4850
- Comments on PR with status
4951

@@ -52,24 +54,27 @@ This directory contains GitHub Actions workflows for the DisTrack VS Code Extens
5254
**Purpose:** Monitors dependencies for security updates
5355

5456
- Checks for outdated dependencies
55-
- Runs security audits
5657
- Creates issues for high/critical security vulnerabilities
5758
- Helps maintain security posture
5859

5960
## Required Secrets
6061

6162
To use these workflows, you'll need to set up the following secrets in your GitHub repository:
6263

64+
### `TOKEN` (Required for releases)
65+
- **Purpose:** GitHub Personal Access Token for creating releases
66+
- **How to get:**
67+
1. Go to GitHub Settings > Developer settings > Personal access tokens
68+
2. Create a token with `repo` permissions
69+
3. Add it to your repository secrets as `TOKEN`
70+
6371
### `VSCE_PAT` (Required for publishing)
6472
- **Purpose:** Personal Access Token for VS Code Marketplace
6573
- **How to get:**
6674
1. Go to https://dev.azure.com
6775
2. Create a Personal Access Token with Marketplace (Publish) permissions
6876
3. Add it to your repository secrets
6977

70-
### Optional Secrets
71-
- `DISCORD_WEBHOOK_URL`: Discord webhook URL for notifications (if you want Discord integration)
72-
7378
## Usage
7479

7580
### Creating a Release
@@ -78,14 +83,25 @@ To use these workflows, you'll need to set up the following secrets in your GitH
7883
3. Create and push a tag: `git tag v1.0.0 && git push origin v1.0.0`
7984
4. The release workflow will automatically:
8085
- Build the extension
81-
- Create a GitHub release
86+
- Create a draft GitHub release with comprehensive notes
8287
- Package the VSIX file
88+
- Include detailed usage instructions and troubleshooting guide
8389
- Publish to VS Code Marketplace (if VSCE_PAT is configured)
8490

8591
### Manual Workflow Dispatch
8692
- The Dependency Update workflow can be run manually from the Actions tab
8793
- Useful for checking dependencies outside the weekly schedule
8894

95+
## Release Notes Features
96+
97+
The release workflow now generates comprehensive release notes that include:
98+
99+
- **Full Changelog**: Links to the complete CHANGELOG.md
100+
- **Patch Notes**: Extracted from CHANGELOG.md for the specific version
101+
- **Usage Instructions**: Step-by-step guide for setting up and using the extension
102+
- **Troubleshooting**: Common error messages and their solutions
103+
- **Installation Guide**: Complete process from unzipping to running the extension
104+
89105
## Workflow Dependencies
90106

91107
```
@@ -95,7 +111,7 @@ Release ← Publish
95111

96112
The workflows are designed to work together:
97113
- CI runs on every push and PR
98-
- Release creates releases when tags are pushed
114+
- Release creates draft releases when tags are pushed
99115
- Publish automatically publishes to marketplace when releases are created
100116
- PR Check provides feedback on pull requests
101117
- Dependency Update monitors security
@@ -105,7 +121,7 @@ The workflows are designed to work together:
105121
### Common Issues
106122
1. **Build fails**: Check Node.js version compatibility
107123
2. **Publish fails**: Verify VSCE_PAT secret is correctly set
108-
3. **Tests fail**: Ensure all tests pass locally before pushing
124+
3. **Release fails**: Verify TOKEN secret is correctly set
109125
4. **Linting fails**: Run `npm run lint` locally to fix issues
110126

111127
### Local Testing
@@ -114,6 +130,5 @@ Before pushing, run these commands locally:
114130
npm ci
115131
npm run lint
116132
npm run compile
117-
npm run test
118133
npm run package
119134
```

‎.github/workflows/release.yml‎

Lines changed: 124 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,129 @@
11
name: Release
22

33
on:
4-
push:
5-
tags:
6-
- 'v*'
4+
push:
5+
tags:
6+
- "v*"
77

88
jobs:
9-
release:
10-
runs-on: ubuntu-latest
11-
12-
steps:
13-
- name: Checkout code
14-
uses: actions/checkout@v4
15-
16-
- name: Use Node.js
17-
uses: actions/setup-node@v4
18-
with:
19-
node-version: '20.x'
20-
cache: 'npm'
21-
22-
- name: Install dependencies
23-
run: npm ci
24-
25-
- name: Run linting
26-
run: npm run lint
27-
28-
- name: Compile TypeScript
29-
run: npm run compile
30-
31-
# - name: Run tests
32-
# run: npm run test
33-
34-
- name: Build extension
35-
run: npm run package
36-
37-
- name: Package VSIX
38-
run: npx vsce package
39-
40-
- name: Create Release
41-
uses: softprops/action-gh-release@v2
42-
with:
43-
files: |
44-
*.vsix
45-
dist/
46-
generate_release_notes: true
47-
draft: true
48-
prerelease: true
49-
env:
50-
GITHUB_TOKEN: ${{ secrets.TOKEN }}
51-
52-
- name: Upload VSIX artifact
53-
uses: actions/upload-artifact@v4
54-
with:
55-
name: extension-vsix
56-
path: '*.vsix'
57-
retention-days: 30
9+
release:
10+
runs-on: ubuntu-latest
11+
12+
steps:
13+
- name: Checkout code
14+
uses: actions/checkout@v4
15+
16+
- name: Use Node.js
17+
uses: actions/setup-node@v4
18+
with:
19+
node-version: "20.x"
20+
cache: "npm"
21+
22+
- name: Install dependencies
23+
run: npm ci
24+
25+
- name: Run linting
26+
run: npm run lint
27+
28+
- name: Compile TypeScript
29+
run: npm run compile
30+
31+
# - name: Run tests
32+
# run: npm run test
33+
34+
- name: Build extension
35+
run: npm run package
36+
37+
- name: Package VSIX
38+
run: npx vsce package
39+
40+
- name: Generate Release Notes
41+
id: generate_notes
42+
run: |
43+
VERSION=${GITHUB_REF#refs/tags/}
44+
CHANGELOG_CONTENT=$(cat CHANGELOG.md)
45+
46+
cat > release_notes.md << 'EOF'
47+
# DisTrack v$VERSION Release
48+
49+
**Full Changelog**: https://github.com/JayNightmare/DisTrack-VSCode-Extension/blob/master/CHANGELOG.md
50+
51+
## Patch Notes
52+
$CHANGELOG_CONTENT
53+
54+
# How to use release
55+
1. Unzip folder
56+
2. Open folder in VSCode
57+
3. Open Terminal inside VSCode -> Use Command Prompt or Git Bash
58+
4. Run the following
59+
- `npm install` -> Doesn't work? Install [Node](https://nodejs.org/en)
60+
- `mkdir assets` -> Creates a folder called assets
61+
- `cd assets` -> Goes inside the assets folder
62+
- `type nul > link.txt` -> Creates an empty file called link.txt
63+
- `type nul > discord.txt` -> Creates an empty file called discord.txt
64+
5. Open link.txt and enter your back-end server -> Don't have one? Get one [here](https://github.com/JayNightmare/VSCode-Endpoint-Server-Deployment)
65+
6. Open discord.txt and enter your discord bot token -> Don't have one? Get one [here](https://discord.com/developers/applications)
66+
7. Go to the `Run and Debug` tab in VSCode and make sure that `Run Extension` is present
67+
- If it doesn't appear, go to .vscode and open launch.json.
68+
- Ensure launch.json has this code:
69+
```
70+
{
71+
"version": "0.2.0",
72+
"configurations": [
73+
{
74+
"name": "Run Extension",
75+
"type": "extensionHost",
76+
"request": "launch",
77+
"args": [
78+
"--extensionDevelopmentPath=${workspaceFolder}"
79+
],
80+
"outFiles": [
81+
"${workspaceFolder}/dist/**/*.js"
82+
],
83+
"preLaunchTask": "${defaultBuildTask}"
84+
}
85+
]
86+
}
87+
```
88+
8. Before running, put `<<` in the filter so it only shows the extension
89+
9. A successful run should show no read text.
90+
10. Open Terminal and run `vsce`
91+
11. Run `vsce package`, this will create the vscode extension. Should output as `dis-track-$VERSION.vsix`
92+
12. Press `Ctrl+Shift+P` (or click the top search bar than press `>`) and type `Extensions: Install From VSIX`
93+
13. Open the .vsix file
94+
14. Enjoy your very own Dis.Track Extension
95+
96+
# Different Errors you could encounter:
97+
98+
Error Name | Reason | Solution
99+
------------- | ------------- | -------------
100+
`Failed to send session data: TypeError: Invalid URL` | Your link.txt url does not work | Check your url is accessible. If it needs a header, you will need to adjust the api.ts file to account for this. If url is correct, use [Postman](https://web.postman.co/workspace/create) and try sending data to it using `POST [endpoint url]/coding-sessions`. Once you are able to send data, retry extension.
101+
`Failed to fetch language durations: TypeError: Invalid URL` | Your link.txt url does not work | Check your url is accessible. If it needs a header, you will need to adjust the api.ts file to account for this. If url is correct, use [Postman](https://web.postman.co/workspace/create) and try fetching data to it. Do `GET [endpoint url]/user-profile/:userId`. Once you are able to receive data, retry extension.
102+
`Failed to fetch streak data: TypeError: Invalid URL` | Your link.txt url does not work | Check your url is accessible. If it needs a header, you will need to adjust the api.ts file to account for this.
103+
`Failed to fetch leaderboard: TypeError: Invalid URL` | Your link.txt url does not work | Check your url is accessible. If it needs a header, you will need to adjust the api.ts file to account for this. If url is correct, use [Postman](https://web.postman.co/workspace/create) and try fetching data to it. Do `GET [endpoint url]/leaderboard`. Once you are able to receive data, retry extension.
104+
`Bot Token Null` | Your discord.txt Bot Token doesn't work | Check that the bot token is valid. To get one, go to the application > Settings > Bot > Token
105+
EOF
106+
107+
echo "notes<<EOF" >> $GITHUB_OUTPUT
108+
cat release_notes.md >> $GITHUB_OUTPUT
109+
echo "EOF" >> $GITHUB_OUTPUT
110+
111+
- name: Create Release
112+
uses: softprops/action-gh-release@v2
113+
env:
114+
GITHUB_TOKEN: ${{ secrets.TOKEN }}
115+
with:
116+
files: |
117+
*.vsix
118+
dist/
119+
body: ${{ steps.generate_notes.outputs.notes }}
120+
generate_release_notes: false
121+
draft: true
122+
prerelease: true
123+
124+
- name: Upload VSIX artifact
125+
uses: actions/upload-artifact@v4
126+
with:
127+
name: extension-vsix
128+
path: "*.vsix"
129+
retention-days: 30

0 commit comments

Comments
 (0)