|
| 1 | +# Release workflow |
| 2 | + |
| 3 | +The process of releasing a new version involves several steps: |
| 4 | + |
| 5 | +1. [Install SDGym from source](#install-sdgym-from-source) |
| 6 | + |
| 7 | +2. [Linting and tests](#linting-and-tests) |
| 8 | + |
| 9 | +3. [Make a release candidate](#make-a-release-candidate) |
| 10 | + |
| 11 | +4. [Milestone](#milestone) |
| 12 | + |
| 13 | +5. [Update HISTORY](#update-history) |
| 14 | + |
| 15 | +6. [Check the release](#check-the-release) |
| 16 | + |
| 17 | +7. [Update stable branch and bump version](#update-stable-branch-and-bump-version) |
| 18 | + |
| 19 | +8. [Create the Release on GitHub](#create-the-release-on-github) |
| 20 | + |
| 21 | +9. [Close milestone and create new milestone](#close-milestone-and-create-new-milestone) |
| 22 | + |
| 23 | +## Install SDGym from source |
| 24 | + |
| 25 | +Clone the project and install the development requirements before starting the release process. Alternatively, with your virtualenv activated: |
| 26 | + |
| 27 | +```bash |
| 28 | +git clone https://github.com/sdv-dev/SDGym.git |
| 29 | +cd SDGym |
| 30 | +git checkout main |
| 31 | +make install-develop |
| 32 | +``` |
| 33 | + |
| 34 | +## Linting and tests |
| 35 | + |
| 36 | +Execute the tests and linting. The tests must end with no errors: |
| 37 | + |
| 38 | +```bash |
| 39 | +make test && make lint |
| 40 | +``` |
| 41 | + |
| 42 | +And you will see something like this: |
| 43 | + |
| 44 | +``` |
| 45 | +Coverage XML written to file ./integration_cov.xml |
| 46 | +============ 242 passed, 166 warnings, 134 subtests passed in 9.88s ============ |
| 47 | +.... |
| 48 | +invoke lint |
| 49 | +No broken requirements found. |
| 50 | +All checks passed! |
| 51 | +80 files already formatted |
| 52 | +``` |
| 53 | + |
| 54 | +The execution has finished with no errors, 0 test skipped and 166 warnings. |
| 55 | + |
| 56 | +## Make a release candidate |
| 57 | + |
| 58 | +1. On the SDGym GitHub page, navigate to the [Actions][actions] tab. |
| 59 | +2. Select the `Release` action. |
| 60 | +3. Run it on the main branch. Make sure `Release candidate` is checked and `Test PyPI` is not. |
| 61 | +4. Check on [PyPI][sdgym-pypi] to assure the release candidate was successfully uploaded. |
| 62 | + - You should see X.Y.ZdevN PRE-RELEASE |
| 63 | + |
| 64 | +[actions]: https://github.com/sdv-dev/SDGym/actions |
| 65 | +[sdgym-pypi]: https://pypi.org/project/SDGym/#history |
| 66 | + |
| 67 | +## Milestone |
| 68 | + |
| 69 | +It's important to check that the GitHub and milestone issues are up to date with the release. |
| 70 | + |
| 71 | +You neet to check that: |
| 72 | + |
| 73 | +- The milestone for the current release exists. |
| 74 | +- All the issues closed since the latest release are associated to the milestone. If they are not, associate them. |
| 75 | +- All the issues associated to the milestone are closed. If there are open issues but the milestone needs to |
| 76 | + be released anyway, move them to the next milestone. |
| 77 | +- All the issues in the milestone are assigned to at least one person. |
| 78 | +- All the pull requests closed since the latest release are associated to an issue. If necessary, create issues |
| 79 | + and assign them to the milestone. Also assign the person who opened the issue to them. |
| 80 | + |
| 81 | +## Update HISTORY |
| 82 | +Run the [Release Prep](https://github.com/sdv-dev/SDGym/actions/workflows/prepare_release.yml) workflow. This workflow will create a pull request with updates to HISTORY.md |
| 83 | + |
| 84 | +Make sure HISTORY.md is updated with the issues of the milestone: |
| 85 | + |
| 86 | +``` |
| 87 | +# History |
| 88 | +
|
| 89 | +## X.Y.Z (YYYY-MM-DD) |
| 90 | +
|
| 91 | +### New Features |
| 92 | +
|
| 93 | +* <ISSUE TITLE> - [Issue #<issue>](https://github.com/sdv-dev/SDGym/issues/<issue>) by @resolver |
| 94 | +
|
| 95 | +### General Improvements |
| 96 | +
|
| 97 | +* <ISSUE TITLE> - [Issue #<issue>](https://github.com/sdv-dev/SDGym/issues/<issue>) by @resolver |
| 98 | +
|
| 99 | +### Bug Fixed |
| 100 | +
|
| 101 | +* <ISSUE TITLE> - [Issue #<issue>](https://github.com/sdv-dev/SDGym/issues/<issue>) by @resolver |
| 102 | +``` |
| 103 | + |
| 104 | +The issue list per milestone can be found [here][milestones]. |
| 105 | + |
| 106 | +[milestones]: https://github.com/sdv-dev/SDGym/milestones |
| 107 | + |
| 108 | +Put the pull request up for review and get 2 approvals to merge into `main`. |
| 109 | + |
| 110 | +## Check the release |
| 111 | +Once HISTORY.md has been updated on `main`, check if the release can be made: |
| 112 | + |
| 113 | +```bash |
| 114 | +make check-release |
| 115 | +``` |
| 116 | + |
| 117 | +## Update stable branch and bump version |
| 118 | +The `stable` branch needs to be updated with the changes from `main` and the version needs to be bumped. |
| 119 | +Depending on the type of release, run one of the following: |
| 120 | + |
| 121 | +* `make release`: This will release a patch, which is the most common type of release. Use this when the changes are bugfixes or enhancements that do not modify the existing user API. Changes that modify the user API to add new features but that do not modify the usage of the previous features can also be released as a patch. |
| 122 | +* `make release-minor`: This will release the next minor version. Use this if the changes modify the existing user API in any way, even if it is backwards compatible. Minor backwards incompatible changes can also be released as minor versions while the library is still in beta state. After the major version 1 has been released, minor version can only be used to add backwards compatible API changes. |
| 123 | +* `make release-major`: This will release the next major version. Use this to if the changes modify the user API in a backwards incompatible way after the major version 1 has been released. |
| 124 | + |
| 125 | +Running one of these will **push commits directly** to `main`. |
| 126 | +At the end, you should see the 3 commits on `main` (from oldest to newest): |
| 127 | +- `make release-tag: Merge branch 'main' into stable` |
| 128 | +- `Bump version: X.Y.Z.devN → X.Y.Z` |
| 129 | +- `Bump version: X.Y.Z -> X.Y.A.dev0` |
| 130 | + |
| 131 | +## Create the Release on GitHub |
| 132 | + |
| 133 | +After the update to HISTORY.md is merged into `main` and the version is bumped, it is time to [create the release GitHub](https://github.com/sdv-dev/SDGym/releases/new). |
| 134 | +- Create a new tag with the version number with a v prefix (e.g. v0.3.1) |
| 135 | +- The target should be the `stable` branch |
| 136 | +- Release title is the same as the tag (e.g. v0.3.1) |
| 137 | +- This is not a pre-release (`Set as a pre-release` should be unchecked) |
| 138 | + |
| 139 | +Click `Publish release`, which will kickoff the release workflow and automatically upload the package to [public PyPI](https://pypi.org/project/sdgym/). |
| 140 | + |
| 141 | +## Close milestone and create new milestone |
| 142 | + |
| 143 | +Finaly, **close the milestone** and, if it does not exist, **create the next milestone**. |
0 commit comments