|
1 | 1 | # Release Process |
2 | 2 |
|
3 | | -This document outlines the process for creating new releases of the Glean CLI. |
| 3 | +## Setup |
4 | 4 |
|
5 | | -## Versioning |
| 5 | +After cloning the repository, run the following command to install required dependencies: |
6 | 6 |
|
7 | | -We follow [Semantic Versioning](https://semver.org/) (SemVer): |
8 | | -- MAJOR version (X.0.0) - incompatible API changes |
9 | | -- MINOR version (0.X.0) - add functionality in a backward compatible manner |
10 | | -- PATCH version (0.0.X) - backward compatible bug fixes |
11 | | - |
12 | | -## Prerequisites |
13 | | - |
14 | | -Install the required tools: |
15 | 7 | ```bash |
16 | | -# Install svu for automated versioning |
17 | | -go install github.com/caarlos0/svu@latest |
| 8 | +task setup |
18 | 9 | ``` |
19 | 10 |
|
20 | | -## Release Steps |
21 | | - |
22 | | -You can create a new release using either the automated task or the manual steps below. |
23 | | - |
24 | | -### Automated Release |
25 | | - |
26 | | -```bash |
27 | | -# This will run all checks, create and push the tag |
28 | | -task release |
29 | | -``` |
30 | | - |
31 | | -### Manual Steps |
32 | | - |
33 | | -If you need more control over the release process, you can follow these steps manually: |
| 11 | +This will install: |
| 12 | +- `svu` - for semantic versioning and tag management |
| 13 | +- `gotestsum` - for improved test output and summaries |
| 14 | +- `golangci-lint` - for code linting |
34 | 15 |
|
35 | | -1. **Ensure Main Branch is Ready** |
36 | | - ```bash |
37 | | - git checkout main |
38 | | - git pull origin main |
39 | | - ``` |
| 16 | +## Creating a Release |
40 | 17 |
|
41 | | -2. **Run Tests and Checks** |
42 | | - ```bash |
43 | | - task test |
44 | | - task lint |
45 | | - ``` |
| 18 | +To create a new release: |
46 | 19 |
|
47 | | -3. **Create Release** |
| 20 | +1. Ensure your working directory is clean and you're on the `main` branch |
| 21 | +2. Run the release task: |
48 | 22 | ```bash |
49 | | - # Preview the next version based on conventional commits |
50 | | - svu next |
51 | | - |
52 | | - # Create and push the tag with the next version |
53 | | - git tag -a $(svu next) -m "Release $(svu next)" |
54 | | - git push origin $(svu next) |
| 23 | + task release |
55 | 24 | ``` |
56 | 25 |
|
57 | | - Note: `svu` automatically determines the next version based on your commit messages: |
58 | | - - `feat:` -> MINOR version bump |
59 | | - - `fix:` -> PATCH version bump |
60 | | - - `BREAKING CHANGE:` in commit body -> MAJOR version bump |
61 | | - |
62 | | -4. **Monitor Release Process** |
63 | | - - The GitHub Action will automatically: |
64 | | - - Create a GitHub release |
65 | | - - Build binaries for all supported platforms |
66 | | - - Generate release notes from commits |
67 | | - - Upload artifacts to the release |
68 | | - - Update the Homebrew formula |
69 | | - |
70 | | -5. **Verify Release** |
71 | | - - Check the [GitHub releases page](https://github.com/scalvert/glean-cli/releases) |
72 | | - - Verify Homebrew formula was updated |
73 | | - - Test installation methods: |
74 | | - ```bash |
75 | | - # Homebrew |
76 | | - brew update |
77 | | - brew install scalvert/tap/glean-cli |
78 | | - |
79 | | - # Go Install |
80 | | - go install github.com/scalvert/glean-cli@latest |
81 | | - |
82 | | - # Shell Script |
83 | | - curl -fsSL https://raw.githubusercontent.com/scalvert/glean-cli/main/install.sh | sh |
84 | | - ``` |
| 26 | + This will: |
| 27 | + - Run all checks (lint, test, build) |
| 28 | + - Show the current version and commits since last release |
| 29 | + - Calculate and propose the next version |
| 30 | + - Create and push a git tag |
| 31 | + - Trigger the release workflow |
85 | 32 |
|
86 | | -## Release Artifacts |
| 33 | +### Optional Parameters |
87 | 34 |
|
88 | | -Each release includes: |
89 | | -- Binary distributions for: |
90 | | - - macOS (x86_64, arm64) |
91 | | - - Linux (x86_64, arm64) |
92 | | - - Windows (x86_64, arm64) |
93 | | -- Source code (zip, tar.gz) |
94 | | -- Checksums file |
95 | | -- Changelog |
96 | | - |
97 | | -## Commit Convention |
98 | | - |
99 | | -To make the most of automated versioning, follow these commit message conventions: |
100 | | - |
101 | | -``` |
102 | | -<type>: <description> |
103 | | - |
104 | | -[optional body] |
105 | | - |
106 | | -[optional footer(s)] |
107 | | -``` |
108 | | -
|
109 | | -Types: |
110 | | -- `feat:` - New feature (MINOR version bump) |
111 | | -- `fix:` - Bug fix (PATCH version bump) |
112 | | -- `docs:` - Documentation only changes |
113 | | -- `style:` - Changes that do not affect the meaning of the code |
114 | | -- `refactor:` - Code change that neither fixes a bug nor adds a feature |
115 | | -- `perf:` - Code change that improves performance |
116 | | -- `test:` - Adding missing tests or correcting existing tests |
117 | | -- `chore:` - Changes to the build process or auxiliary tools |
118 | | -
|
119 | | -Breaking Changes: |
120 | | -- Add `BREAKING CHANGE:` to the commit body to trigger a MAJOR version bump |
121 | | -- Example: |
| 35 | +- Specify a version: |
| 36 | + ```bash |
| 37 | + task release VERSION=v1.2.3 |
122 | 38 | ``` |
123 | | - feat: change API endpoint structure |
124 | 39 |
|
125 | | - BREAKING CHANGE: The API endpoint structure has changed from /v1/* to /api/v1/* |
| 40 | +- Force update an existing tag: |
| 41 | + ```bash |
| 42 | + task release VERSION=v1.2.3 FORCE=true |
126 | 43 | ``` |
127 | 44 |
|
128 | | -## Troubleshooting |
129 | | -
|
130 | | -1. **GitHub Action Failed** |
131 | | - - Check the Action logs for errors |
132 | | - - Ensure GITHUB_TOKEN has required permissions |
133 | | - - Verify the tag follows the format `v*` (e.g., v1.0.0) |
134 | | -
|
135 | | -2. **Homebrew Update Failed** |
136 | | - - Check if homebrew-tap repository exists |
137 | | - - Verify repository permissions |
138 | | - - Check the "Update Homebrew tap" step in the Action logs |
139 | | -
|
140 | | -3. **Bad Release** |
141 | | - If a release has issues: |
142 | | - ```bash |
143 | | - # Get current version |
144 | | - current_version=$(svu current) |
145 | | -
|
146 | | - # Delete tag locally |
147 | | - git tag -d $current_version |
148 | | -
|
149 | | - # Delete tag remotely |
150 | | - git push --delete origin $current_version |
151 | | - ``` |
152 | | - Then fix the issues and retry the release process. |
153 | | - |
154 | | -## Notes |
| 45 | +## Monitoring |
155 | 46 |
|
156 | | -- Release notes are automatically generated from commit messages |
157 | | -- Commits starting with `docs:`, `test:`, `ci:` are excluded from release notes |
158 | | -- The release process is automated via GitHub Actions |
159 | | -- Binary distributions are built using GoReleaser |
160 | | -- All releases are automatically published to GitHub Releases |
| 47 | +After creating a release: |
| 48 | +1. The GitHub Actions workflow will be triggered automatically |
| 49 | +2. Monitor the release at: https://github.com/scalvert/glean-cli/actions |
| 50 | +3. Once complete, the release will be available at: https://github.com/scalvert/glean-cli/releases |
0 commit comments