|
1 | 1 | # How to issue an ActivitySim release |
2 | 2 |
|
3 | | -> **WARNING: These instructions are incomplete.** |
4 | | -
|
5 | | -01. Check that the branch you intend to release is passing tests on Travis. |
6 | | - If it's not passing there you should not release it. |
| 3 | +00. Check that the main branch is passing tests, especially the "core tests" on |
| 4 | + [GitHub Actions](https://github.com/ActivitySim/activitysim/actions/workflows/core_tests.yml). |
| 5 | + It is generally the policy that the main branch should always be passing tests, |
| 6 | + becuase PRs must pass tests before they can be merged. However, it is |
| 7 | + possible that tests may fail after a PR is merged, so it is important to |
| 8 | + double-check that the main branch is passing tests before issuing a release. |
7 | 9 |
|
8 | 10 | 00. Start from a completely clean conda environment |
9 | 11 | and git repository. Assuming you have `conda` installed, you can do so |
10 | 12 | by starting where ActivitySim is not yet cloned (e.g. in an empty |
11 | 13 | directory) and running: |
12 | 14 | ```sh |
13 | | - conda create -n TEMP-ASIM-DEV python=3.10 git gh -c conda-forge --override-channels |
14 | | - conda activate TEMP-ASIM-DEV |
| 15 | + conda create -p ./TEMP-ASIM-DEV python=3.10 git gh -c conda-forge --override-channels |
| 16 | + conda activate ./TEMP-ASIM-DEV |
15 | 17 | gh auth login # <--- (only needed if gh is not logged in) |
16 | 18 | gh repo clone ActivitySim/activitysim |
17 | 19 | cd activitysim |
18 | 20 | ``` |
19 | 21 |
|
20 | | -00. Per project policy, code on the main branch should have been released, |
21 | | - but if you are *preparing* a release then the code should be on the `develop` |
22 | | - branch. Switch to that branch now, and make sure it is synced to the |
23 | | - version on GitHub: |
24 | | - ```sh |
25 | | - git switch develop |
26 | | - git pull |
27 | | - ``` |
28 | | - |
29 | 22 | 00. Update your Conda environment for testing. We do not want to use an |
30 | | - existing environment on your machine, as it may be out-of-date |
| 23 | + existing environment on your machine, as it may be out-of-sync |
31 | 24 | and we want to make sure everything passes muster using the |
32 | | - most up-to-date dependencies available. The following command |
| 25 | + dependencies as they are available today. The following command |
33 | 26 | will update the active environment (we made this to be `TEMP-ASIM-DEV` |
34 | 27 | if you followed the directions above). |
35 | 28 | ```sh |
|
48 | 41 | black --check --diff . |
49 | 42 | ``` |
50 | 43 |
|
51 | | -00. Run the regular test suite on Windows. Most GitHub Actions tests are done on Linux, |
| 44 | +00. Run the regular test suite on Windows. Most GitHub Actions tests are done on |
52 | 45 | Linux (it's faster to start up and run a new clean VM for testing) but most |
53 | 46 | users are on Windows, and the test suite should also be run on Windows to |
54 | 47 | ensure that it works on that platform as well. If you |
|
67 | 60 | ``` |
68 | 61 |
|
69 | 62 | 00. Test the full-scale regional examples. These examples are big, too |
70 | | - large to run on Travis, and will take a lot of time (many hours) to |
| 63 | + large to run on GitHub Actions, and will take a lot of time (many hours) to |
71 | 64 | download and run. |
72 | 65 | ```sh |
73 | 66 | mkdir tmp-asim |
|
88 | 81 | There are also demo notebooks for estimation, but their functionality |
89 | 82 | is completely tested in the unit tests run previously. |
90 | 83 |
|
91 | | -00. Use bump2version to tag the release commit and update the |
92 | | - version number. The following code will generate a "patch" release, |
93 | | - incrementing the third value in the version number (i.e. "1.2.3" |
94 | | - becomes "1.2.4"). Alternatively, make a "minor" or "major" release. |
95 | | - The `--list` command will generate output to your console to confirm |
96 | | - that the old and new version numbers are what you expect, before you |
97 | | - push the commit (with the changed version in the code) and tags to |
98 | | - GitHub. |
99 | | - ```sh |
100 | | - bump2version patch --list |
101 | | - ``` |
102 | | - |
103 | | - It is also possible to make a development pre-release. To do so, |
104 | | - explicitly set the version number to the next patch plus a ".devN" |
105 | | - suffix: |
106 | | - |
| 84 | +00. Tag the release commit with the new version number. ActivitySim uses |
| 85 | + dynamic versioning, so the version number is not stored in a file but |
| 86 | + is instead read from the most recent git tag, so it is important to tag |
| 87 | + the repository with the correct version. The following command will |
| 88 | + generate a new tag with the version number "1.2.3" (for example): |
107 | 89 | ```sh |
108 | | - bump2version patch --new-version 1.2.3.dev0 --list |
109 | | - ``` |
110 | | - |
111 | | - Then, when ready to make a "final" release, set the version by |
112 | | - explicitly removing the suffix: |
113 | | - ```sh |
114 | | - bump2version patch --new-version 1.2.3 --list |
| 90 | + git -a v1.2.3 -m "Release v1.2.3" |
115 | 91 | ``` |
116 | 92 |
|
117 | 93 | 00. Push the tagged commit to GitHub. |
118 | 94 | ```sh |
119 | 95 | git push --tags |
120 | 96 | ``` |
121 | 97 |
|
122 | | -00. For non-development releases, open a pull request to merge the proposed |
123 | | - release into main. The following command will open a web browser for |
124 | | - you to create the pull request. |
125 | | - ```sh |
126 | | - gh pr create --web |
127 | | - ``` |
128 | | - After creating the PR, confirm with the ActivitySim PMC that the release |
129 | | - is ready before actually merging it. |
130 | | - |
131 | | - Once final approval is granted, merge the PR into main. The presence |
132 | | - of the git tags added earlier will trigger automated build steps to |
133 | | - prepare and deploy the release to pypi and conda-forge. |
134 | | - |
135 | | -00. Create a "release" on GitHub. |
| 98 | +00. Create a "release" on GitHub. You can do this from the command line using |
| 99 | + the `gh` command line tool: |
136 | 100 | ```sh |
137 | 101 | gh release create v1.2.3 |
138 | 102 | ``` |
| 103 | + But it may be easier to do this through the |
| 104 | + [GitHub web interface](https://github.com/ActivitySim/activitysim/releases/new), |
| 105 | + where you can select the tag you just created and add a title and description. |
| 106 | + Both the interactive command line tool shown above and the web interface include |
| 107 | + the ability to create release notes automatically from the commit messages of |
| 108 | + all accepted PRs since the last release, but you may want to add additional |
| 109 | + notes to the release to highlight important changes or new features. |
| 110 | + |
139 | 111 | The process of creating and tagging a release will automatically |
140 | 112 | trigger various GitHub Actions scripts to build, test, and publish the |
141 | 113 | new release to PyPI and conda forge, assuming there are no errors. |
142 | 114 |
|
143 | | - For a development pre-release, include the `--prerelease` argument. |
144 | | - As the project's policy is that only formally released code is merged |
145 | | - to the main branch, any pre-release should also be built against a |
146 | | - non-default branch. For example, to pre-release from the `develop` |
147 | | - branch: |
148 | | - ```sh |
149 | | - gh release create v1.2.3.dev0 \ |
150 | | - --prerelease \ |
151 | | - --target develop \ |
152 | | - --notes "this pre-release is for a cool new feature" \ |
153 | | - --title "Development Pre-Release" |
154 | | - ``` |
| 115 | +00. If the dependencies of ActivitySim have changed, also be sure to update the |
| 116 | + dependencies of the conda-forge [recipe](https://github.com/conda-forge/activitysim-feedstock/tree/main/recipe). |
| 117 | + If the dependencies of ActivitySim have not changed, the conda-forge version |
| 118 | + of ActivitySim should auto-update within a few hours of making the release on |
| 119 | + Github. |
| 120 | + |
| 121 | +00. Build the ActivitySim Standalone Windows Installer. This is done using |
| 122 | + GitHub Actions, but it is not done automatically when a release is created, |
| 123 | + instead it requires a manual workflow dispatch trigger. You can do this by |
| 124 | + going to the [build_installer workflow page](https://github.com/ActivitySim/activitysim/actions/workflows/build_installer.yml) |
| 125 | + and clicking on the "Run workflow" button. You will need to provide the |
| 126 | + version number and choose to add the built installer to the release. |
155 | 127 |
|
156 | 128 | 00. Clean up your workspace, including removing the Conda environment used for |
157 | 129 | testing (which will prevent you from accidentally using an old |
158 | 130 | environment when you should have a fresh up-to-date one next time). |
159 | 131 | ```sh |
160 | 132 | conda deactivate |
161 | | - conda env remove -n TEMP-ASIM-DEV |
| 133 | + conda env remove -p ./TEMP-ASIM-DEV |
162 | 134 | ``` |
0 commit comments