|
1 | | -# workflows |
2 | | - |
3 | | -Goal: |
4 | | - |
5 | | -1. Follow github flow, e.g. PRs into mainline branch. |
6 | | -2. Release of mainline |
7 | | -3. Keep a change log, whose version numbers are automatically updated when a release is pushed |
8 | | -4. Automatically create github releases, add tags to repo |
9 | | -5. Automatically push nightly builds on push to mainline to GPR |
10 | | -6. Allow for live documentation to be updated independently of releases |
11 | | -7. Allow for docs to be updated with a release. |
12 | | -8. Release workflows should be idempotent, be re-runable in case of errors |
13 | | - |
14 | | -## common verification steps in PR / build on mainline |
15 | | -1. build |
16 | | -2. test |
17 | | -3. verify template |
18 | | -4. build docs |
19 | | -5. build nuget packages |
20 | | - |
21 | | -## Changes to code or documentation for next release: |
22 | | - |
23 | | -1. Build of mainline |
24 | | -2. Create PR, include update to changelog.md |
25 | | - |
26 | | -## On merge to mail |
27 | | - |
28 | | -1. Run code analyzers |
29 | | -2. build nuget packages |
30 | | -3. push nightly nuget packages to github package repository |
31 | | - |
32 | | -## Create a release: |
33 | | - |
34 | | -1. Trigger prepare-release workflow (input: versionIncrement, releaseImmediately): |
35 | | -2. nbgv prepare-release --versionIncrement versionIncrement |
36 | | -3. $version = nbgv get-version |
37 | | -4. git push main |
38 | | -5. git checkout release/($version) |
39 | | -6. push release branch |
40 | | - |
41 | | -## Release |
42 | | - |
43 | | -1. build |
44 | | -2. test |
45 | | -3. verify template |
46 | | -4. build docs |
47 | | -5. build nuget packages |
48 | | -6. update changelog.md with new version ($version) using keep-a-changelog-new-release |
49 | | -7. Create version tag |
50 | | -8. get version |
51 | | -9. read changelog from https://github.com/mindsers/changelog-reader-action |
52 | | -10. create github release with tag, title, and description |
53 | | -11. Build nuget packages |
54 | | -12. push nuget packages |
55 | | -13. merge release branch with origin:mainline |
56 | | -14. merge mainline to docs_live |
57 | | -15. merge release branch with origin:docs_live |
58 | | -16. delete release branch |
59 | | - |
60 | | -## Updates to live docs |
61 | | - |
62 | | -1. On push (merge of PR or direct push) to docs_live branch |
63 | | - 1. build docs and push to GH Pages |
64 | | - 2. merge with FF back to main |
65 | | - 3. if merge fails, create PR from docs_live to mainline |
| 1 | +# Workflows |
| 2 | + |
| 3 | +The workflows have the goal of automating as much as possible, while keeping workflows flexible to handle odd cases when needed. |
| 4 | + |
| 5 | +The goals are: |
| 6 | + |
| 7 | +1. Follow GitHub flow, e.g. PRs into mainline branch (mainline is whatever is the default branch in a GitHub repository). |
| 8 | +2. Mainline has latest preview/nightly code in unreleased form, and new preview releases is automatically pushed to GitHub Package Repository when source code changes in mainline. |
| 9 | +3. `stable` branch contains latest released code to NuGet.org. |
| 10 | +4. Use "[Keep a change log](https://keepachangelog.com/en/1.0.0/), where mainline has new items in "Unreleased" section, that are automatically moved to a "released versioned" section when released. |
| 11 | +5. Use "[Nerdbank.GitVersioning](https://github.com/dotnet/Nerdbank.GitVersioning)" to correctly stamp versions, repository references, and commit references in .NET assemblies of both releases and prereleases. |
| 12 | +7. Automatically create GitHub releases and add tags on new release. |
| 13 | +8. Allow for live documentation to be updated independently of releases from stable. |
| 14 | +9. Allow for changes to docs to be updated with a release. |
| 15 | +10. Release workflows should be idempotent, be re-runable in case of errors. |
| 16 | + |
| 17 | +The following sections will list what should happen in the different scenarios involved. |
| 18 | + |
| 19 | +## Changes to code or documentation for next release stored in mainline: |
| 20 | + |
| 21 | +1. Locally, make changes from mainline branch. remember to update CHANGELOG.md. |
| 22 | +2. Push to mainline or create a PR targeting mainline, if not authorized to push directly. |
| 23 | + |
| 24 | +## On push/pull request merged on mainline |
| 25 | + |
| 26 | +1. Automatically trigger `verification` workflow. |
| 27 | +2. Automatically trigger `release-preview` workflow if `verification` workflow successed. |
| 28 | + |
| 29 | +## On pull request (created, updated) to mainline |
| 30 | + |
| 31 | +1. Automatically trigger `verification` workflow. |
| 32 | + |
| 33 | +## Prepare a new release: |
| 34 | + |
| 35 | +Manually trigger `prepare-release` workflow, specifying if it is a `minor` or `major` release. This does the following: |
| 36 | + |
| 37 | +1. Check that release contains changes, if not, abort. This is verified by looking at the "Unreleased" section in the CHANGELOG.md. |
| 38 | +2. Increment version.json on mainline, e.g. 1.1-preview to 1.2-preview. Push mainline branch to origin. |
| 39 | +3. Create release branch and set version.json in that to non preview, e.g. 1.1. Push release branch to origin. |
| 40 | +4. Create pull request for release branch towards `stable`. |
| 41 | + |
| 42 | +Creating the PR ensures `verification` workflow runs, and gives the option to make small adjustments before release if needed. |
| 43 | + |
| 44 | +TODO: |
| 45 | + |
| 46 | +- Make it possible to specify that the release PR should be accepted automatically for immidiate release. |
| 47 | +- Use some tooling like https://github.com/fsprojects/SyntacticVersioning/ or changelog analyser to automatically determine if the release is a minor or major release. |
| 48 | + |
| 49 | +## Release: |
| 50 | + |
| 51 | +Automatically trigger `release` workflow on release PR merged with stable, or if it is triggered manaully. This does the following: |
| 52 | + |
| 53 | +1. Check that release contains changes, if not, abort. This is verified by looking at the "Unreleased" section in the CHANGELOG.md. |
| 54 | +2. Update changelog: move content from "unreleased" section to an "[x.y.c] yyyy-mm-dd" section |
| 55 | +3. Commit CHANGELOG.md to `stable` branch |
| 56 | +4. Building library in release mode |
| 57 | +5. Upload library to NuGet.org repository |
| 58 | +6. Push `stable` branch to origin |
| 59 | +7. Create GitHub release from commit with CHANGELOG.md changes on stable. The release is created with the title and content from the CHANGELOG related to the release. |
| 60 | +8. Merge `stable` with mainline and push to origin |
| 61 | +9. If merge between `stable` and mainline fails, then create a PR from `stable` to mainline instead. |
| 62 | + |
| 63 | +The order of these steps are important as they make sure that GitVersioning correctly stamps the generated assemblies/nuget packages with the right version and github commit hash from when the changelog was updated. |
| 64 | + |
| 65 | +## Updates to live docs on `stable` |
| 66 | + |
| 67 | +If a library has a documentation site, the version of the docs should match the latest released version of the library. This, the source for the docs located on the `stable` branch is where the live documentation website is built from. |
| 68 | + |
| 69 | +Since it is not uncommon that fixes and changes to the docs need to happen between releases, changes to the docs sources are the only changes allowed to be pushed to `stable` outside of normal release pull requests. When this happens, the following should happen: |
| 70 | + |
| 71 | +1. Automatically trigger `docs-deploy` workflow, that builds and uploads docs to whatever hosting solution it uses, e.g. GH Pages. |
| 72 | +2. Merge `stable` with mainline branch, such that updated docs are visible in the mainline branch. |
| 73 | +3. If merge between `stable` and mainline fails, then create a PR from `stable` to mainline instead. |
0 commit comments