|
| 1 | +# Release Process |
| 2 | + |
| 3 | +This project follows [Gitflow](https://nvie.com/posts/a-successful-git-branching-model/) and uses [GitVersion](https://gitversion.net/) (ContinuousDelivery mode) for automatic semantic versioning. NuGet publishing is handled by GitHub Actions on push to `master`. |
| 4 | + |
| 5 | +## Branch Overview |
| 6 | + |
| 7 | +| Branch | Purpose | |
| 8 | +|---|---| |
| 9 | +| `master` | Production releases. Pushes here trigger NuGet publish. | |
| 10 | +| `develop` | Integration branch for the next release. | |
| 11 | +| `feature/*` | Feature branches off `develop`. | |
| 12 | +| `release/*` | Release stabilization branches off `develop`. | |
| 13 | + |
| 14 | +## Release Steps |
| 15 | + |
| 16 | +### 1. Ensure `develop` is ready |
| 17 | + |
| 18 | +- All feature branches for the release are merged into `develop`. |
| 19 | +- CI is green on `develop`. |
| 20 | + |
| 21 | +### 2. Create a release branch |
| 22 | + |
| 23 | +```bash |
| 24 | +git checkout develop |
| 25 | +git pull origin develop |
| 26 | +git checkout -b release/X.Y.Z |
| 27 | +``` |
| 28 | + |
| 29 | +### 3. Finalize the release |
| 30 | + |
| 31 | +On the release branch, make release-only changes: |
| 32 | + |
| 33 | +- **Update target frameworks** in `src/Gotenberg.Sharp.Api.Client/Gotenberg.Sharp.Api.Client.csproj` if adding/dropping TFMs. |
| 34 | +- **Update `PackageReleaseNotes`** in the csproj with a summary of the release. |
| 35 | +- **Update `Description`** in the csproj if the library's capabilities have changed. |
| 36 | +- **Update `CHANGES.MD`** with a full release section listing breaking changes, features, bug fixes, and documentation changes. |
| 37 | +- **Update `README.md`** with a release callout and any new/changed usage examples. |
| 38 | +- Build and run tests locally: |
| 39 | + |
| 40 | +```bash |
| 41 | +dotnet build |
| 42 | +dotnet test |
| 43 | +``` |
| 44 | + |
| 45 | +### 4. Merge release branch into `master` |
| 46 | + |
| 47 | +```bash |
| 48 | +git checkout master |
| 49 | +git pull origin master |
| 50 | +git merge --no-ff release/X.Y.Z |
| 51 | +git tag X.Y.Z |
| 52 | +git push origin master --tags |
| 53 | +``` |
| 54 | + |
| 55 | +This push triggers the GitHub Actions workflow which will: |
| 56 | +1. Build and test against a Gotenberg docker container with basic auth. |
| 57 | +2. Calculate the package version via GitVersion. |
| 58 | +3. Pack the NuGet package (with symbols). |
| 59 | +4. Publish to nuget.org. |
| 60 | + |
| 61 | +### 5. Merge release branch back into `develop` |
| 62 | + |
| 63 | +```bash |
| 64 | +git checkout develop |
| 65 | +git pull origin develop |
| 66 | +git merge --no-ff release/X.Y.Z |
| 67 | +git push origin develop |
| 68 | +``` |
| 69 | + |
| 70 | +### 6. Clean up |
| 71 | + |
| 72 | +```bash |
| 73 | +git branch -d release/X.Y.Z |
| 74 | +git push origin --delete release/X.Y.Z |
| 75 | +``` |
| 76 | + |
| 77 | +### 7. Create a GitHub Release |
| 78 | + |
| 79 | +- Go to **Releases** > **Draft a new release**. |
| 80 | +- Choose the `X.Y.Z` tag. |
| 81 | +- Title: `vX.Y.Z` |
| 82 | +- Body: Copy the corresponding section from `CHANGES.MD`. |
| 83 | +- Publish. |
| 84 | + |
| 85 | +## Hotfix Process |
| 86 | + |
| 87 | +For critical fixes to a released version: |
| 88 | + |
| 89 | +```bash |
| 90 | +git checkout master |
| 91 | +git checkout -b hotfix/X.Y.Z+1 |
| 92 | +# make fix, commit |
| 93 | +git checkout master |
| 94 | +git merge --no-ff hotfix/X.Y.Z+1 |
| 95 | +git tag X.Y.Z+1 |
| 96 | +git push origin master --tags |
| 97 | + |
| 98 | +git checkout develop |
| 99 | +git merge --no-ff hotfix/X.Y.Z+1 |
| 100 | +git push origin develop |
| 101 | + |
| 102 | +git branch -d hotfix/X.Y.Z+1 |
| 103 | +``` |
| 104 | + |
| 105 | +## CI/CD Details |
| 106 | + |
| 107 | +- **Workflow**: `.github/workflows/deploy.yml` |
| 108 | +- **Triggers**: All pushes and pull requests (build + test). NuGet publish only on push to `master`. |
| 109 | +- **Versioning**: GitVersion with `ContinuousDelivery` mode (`GitVersion.yml`). |
| 110 | +- **NuGet API key**: Stored as `NUGETKEY` repository secret. |
| 111 | +- **Test infrastructure**: Gotenberg v8 docker container with basic auth (`testuser`/`testpass`). |
0 commit comments