|
| 1 | +# How to issue an ActivitySim release |
| 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. |
| 7 | + |
| 8 | +00. Start from a completely clean conda environment |
| 9 | + and git repository. Assuming you have `conda` installed, you can do so |
| 10 | + by starting where ActivitySim is not yet cloned (e.g. in an empty |
| 11 | + directory) and running: |
| 12 | + ```sh |
| 13 | + conda create -n TEMP-ASIM-DEV python=3.9 git gh -c conda-forge --override-channels |
| 14 | + conda activate TEMP-ASIM-DEV |
| 15 | + gh auth login # <--- (only needed if gh is not logged in) |
| 16 | + gh repo clone ActivitySim/activitysim |
| 17 | + cd activitysim |
| 18 | + ``` |
| 19 | + |
| 20 | +00. Per project policy, code on the master 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 | +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 |
| 31 | + and we want to make sure everything passes muster using the |
| 32 | + most up-to-date dependencies available. The following command |
| 33 | + will update the active environment (we made this to be `TEMP-ASIM-DEV` |
| 34 | + if you followed the directions above). |
| 35 | + ```sh |
| 36 | + conda env update --file=conda-environments/activitysim-dev.yml |
| 37 | + ``` |
| 38 | + If you add to the ActivitySim dependencies, make sure to also update |
| 39 | + the environments in `conda-environments`, which are used for testing |
| 40 | + and development. If they are not updated, these environments will end |
| 41 | + up with dependencies loaded from *pip* instead of *conda-forge*. |
| 42 | + |
| 43 | +00. Run pycodestyle to ensure that the codebase passes all style checks. |
| 44 | + This check should only take a few seconds. These checks are also done on |
| 45 | + Travis and are platform independent, so they should not be necessary to |
| 46 | + replicate locally, but are listed here for completeness. |
| 47 | + ```sh |
| 48 | + pycodestyle . |
| 49 | + ``` |
| 50 | + |
| 51 | +00. Run the regular test suite on Windows. Travis tests are done on Linux, |
| 52 | + but most users are on Windows, and the test suite should also be run |
| 53 | + on Windows to ensure that it works on that platform as well. If you |
| 54 | + are not preparing this release on Windows, you should be sure to run |
| 55 | + at least through this step on a Windows machine before finalizing a |
| 56 | + release. |
| 57 | + |
| 58 | + A few of the tests require pre-created data that is not included in the |
| 59 | + repository directly, but rather recreated on the fly before testing. The |
| 60 | + regular test suite takes some time to run, between about half an hour and |
| 61 | + two hours depending on the specs of your machine. |
| 62 | + ```sh |
| 63 | + python activitysim/examples/example_multiple_zone/scripts/two_zone_example_data.py |
| 64 | + python activitysim/examples/example_multiple_zone/scripts/three_zone_example_data.py |
| 65 | + pytest . |
| 66 | + ``` |
| 67 | + |
| 68 | +00. Test the full-scale regional examples. These examples are big, too |
| 69 | + large to run on Travis, and will take a lot of time (many hours) to |
| 70 | + download and run. |
| 71 | + ```sh |
| 72 | + mkdir tmp-asim |
| 73 | + cd activitysim/examples |
| 74 | + python create_run_all_examples.py > ../../tmp-asim/run_all_examples.bat |
| 75 | + cd ../../tmp-asim |
| 76 | + call run_all_examples.bat |
| 77 | + ``` |
| 78 | + These tests will run through the gamut even if some of them crash, so |
| 79 | + if you don't sit and watch them go (please don't do this) you'll need |
| 80 | + to scan through the results to make sure there are no errors after the |
| 81 | + fact. |
| 82 | + ```sh |
| 83 | + python ../activitysim/examples/scan_examples_for_errors.py . |
| 84 | + ``` |
| 85 | +
|
| 86 | +00. Test the notebooks in `activitysim/examples/example_mtc/notebooks`. |
| 87 | + There are also demo notebooks for estimation, but their functionality |
| 88 | + is completely tested in the unit tests run previously. |
| 89 | +
|
| 90 | +00. Use bump2version to tag the release commit and update the |
| 91 | + version number. The following code will generate a "patch" release, |
| 92 | + incrementing the third value in the version number (i.e. "1.2.3" |
| 93 | + becomes "1.2.4"). Alternatively, make a "minor" or "major" release. |
| 94 | + The `--list` command will generate output to your console to confirm |
| 95 | + that the old and new version numbers are what you expect, before you |
| 96 | + push the commit (with the changed version in the code) and tags to |
| 97 | + GitHub. |
| 98 | + ```sh |
| 99 | + bump2version patch --list |
| 100 | + ``` |
| 101 | + |
| 102 | + It is also possible to make a development pre-release. To do so, |
| 103 | + explicitly set the version number to the next patch plus a ".devN" |
| 104 | + suffix: |
| 105 | + |
| 106 | + ```sh |
| 107 | + bump2version patch --new-version 1.2.3.dev0 --list |
| 108 | + ``` |
| 109 | + |
| 110 | + Then, when ready to make a "final" release, set the version by |
| 111 | + explicitly removing the suffix: |
| 112 | + ```sh |
| 113 | + bump2version patch --new-version 1.2.3 --list |
| 114 | + ``` |
| 115 | +
|
| 116 | +00. Push the tagged commit to GitHub. |
| 117 | + ```sh |
| 118 | + git push --tags |
| 119 | + ``` |
| 120 | +
|
| 121 | +00. For non-development releases, open a pull request to merge the proposed |
| 122 | + release into master. The following command will open a web browser for |
| 123 | + you to create the pull request. |
| 124 | + ```sh |
| 125 | + gh pr create --web |
| 126 | + ``` |
| 127 | + After creating the PR, confirm with the ActivitySim PMC that the release |
| 128 | + is ready before actually merging it. |
| 129 | + |
| 130 | + Once final approval is granted, merge the PR into master. The presence |
| 131 | + of the git tags added earlier will trigger automated build steps to |
| 132 | + prepare and deploy the release to pypi and conda-forge. |
| 133 | + |
| 134 | +00. Create a "release" on GitHub. |
| 135 | + ```sh |
| 136 | + gh release create v1.2.3 |
| 137 | + ``` |
| 138 | + For a development pre-release, include the `--prerelease` argument. |
| 139 | + As the project's policy is that only formally released code is merged |
| 140 | + to the master branch, any pre-release should also be built against a |
| 141 | + non-default branch. For example, to pre-release from the `develop` |
| 142 | + branch: |
| 143 | + ```sh |
| 144 | + gh release create v1.2.3.dev0 \ |
| 145 | + --prerelease \ |
| 146 | + --target develop \ |
| 147 | + --notes "this pre-release is for a cool new feature" \ |
| 148 | + --title "Development Pre-Release" |
| 149 | + ``` |
| 150 | + |
| 151 | +00. Clean up your workspace, including removing the Conda environment used for |
| 152 | + testing (which will prevent you from accidentally using an old |
| 153 | + environment when you should have a fresh up-to-date one next time). |
| 154 | + ```sh |
| 155 | + conda deactivate |
| 156 | + conda env remove -n TEMP-ASIM-DEV |
| 157 | + ``` |
0 commit comments