release instructions

.github/workflows/core_tests.yml

@@ -8,6 +8,8 @@ on:
   pull_request:
     branches:
       - '*'
+
+  workflow_dispatch:
 
 env:
   CACHE_NUMBER: 0  # increase to reset cache manually
@@ -31,7 +33,9 @@ jobs:
         with:
           auto-update-conda: true
           miniforge-version: latest
+          mamba-version: "2.0.5"
           conda-solver: classic
+          conda-remove-defaults: true
           activate-environment: asim-test
           python-version: ${{ matrix.python-version }}
 
@@ -116,7 +120,9 @@ jobs:
         with:
           auto-update-conda: true
           miniforge-version: latest
+          mamba-version: "2.0.5"
           conda-solver: classic
+          conda-remove-defaults: true
           activate-environment: asim-test
           python-version: ${{ matrix.python-version }}
 
@@ -199,7 +205,9 @@ jobs:
         with:
           auto-update-conda: true
           miniforge-version: latest
+          mamba-version: "2.0.5"
           conda-solver: classic
+          conda-remove-defaults: true
           activate-environment: asim-test
           python-version: ${{ env.python-version }}
 
@@ -287,7 +295,9 @@ jobs:
         with:
           auto-update-conda: true
           miniforge-version: latest
+          mamba-version: "2.0.5"
           conda-solver: classic
+          conda-remove-defaults: true
           activate-environment: asim-test
           python-version: ${{ env.python-version }}
 
@@ -350,7 +360,9 @@ jobs:
         with:
           auto-update-conda: true
           miniforge-version: latest
+          mamba-version: "2.0.5"
           conda-solver: classic
+          conda-remove-defaults: true
           activate-environment: asim-test
           python-version: ${{ env.python-version }}
 
@@ -402,7 +414,9 @@ jobs:
         with:
           auto-update-conda: true
           miniforge-version: latest
+          mamba-version: "2.0.5"
           conda-solver: classic
+          conda-remove-defaults: true
           activate-environment: asim-test
           python-version: ${{ env.python-version }}
 
@@ -461,6 +475,8 @@ jobs:
         uses: conda-incubator/setup-miniconda@v3
         with:
           miniforge-version: latest
+          mamba-version: "2.0.5"
+          conda-remove-defaults: true
           environment-file: conda-environments/docbuild.yml
           python-version: "3.10"
           activate-environment: docbuild

HOW_TO_RELEASE.md

@@ -1,35 +1,28 @@
 # How to issue an ActivitySim release
 
-> **WARNING: These instructions are incomplete.**
-
-01. Check that the branch you intend to release is passing tests on Travis.
-    If it's not passing there you should not release it.
+00. Check that the main branch is passing tests, especially the "core tests" on
+    [GitHub Actions](https://github.com/ActivitySim/activitysim/actions/workflows/core_tests.yml). 
+    It is generally the policy that the main branch should always be passing tests, 
+    becuase PRs must pass tests before they can be merged.  However, it is 
+    possible that tests may fail after a PR is merged, so it is important to
+    double-check that the main branch is passing tests before issuing a release.
 
 00. Start from a completely clean conda environment
     and git repository.  Assuming you have `conda` installed, you can do so
     by starting where ActivitySim is not yet cloned (e.g. in an empty
     directory) and running:
     ```sh
-    conda create -n TEMP-ASIM-DEV python=3.10 git gh -c conda-forge --override-channels
-    conda activate TEMP-ASIM-DEV
+    conda create -p ./TEMP-ASIM-DEV python=3.10 git gh -c conda-forge --override-channels
+    conda activate ./TEMP-ASIM-DEV
     gh auth login   # <--- (only needed if gh is not logged in)
     gh repo clone ActivitySim/activitysim
     cd activitysim
     ```
 
-00. Per project policy, code on the main branch should have been released,
-    but if you are *preparing* a release then the code should be on the `develop`
-    branch.  Switch to that branch now, and make sure it is synced to the
-    version on GitHub:
-    ```sh
-    git switch develop
-    git pull
-    ```
-
 00. Update your Conda environment for testing.  We do not want to use an
-    existing environment on your machine, as it may be out-of-date
+    existing environment on your machine, as it may be out-of-sync
     and we want to make sure everything passes muster using the
-    most up-to-date dependencies available.  The following command
+    dependencies as they are available today.  The following command
     will update the active environment (we made this to be `TEMP-ASIM-DEV`
     if you followed the directions above).
     ```sh
@@ -48,7 +41,7 @@
     black --check --diff .
     ```
 
-00. Run the regular test suite on Windows. Most GitHub Actions tests are done on Linux,
+00. Run the regular test suite on Windows. Most GitHub Actions tests are done on
     Linux (it's faster to start up and run a new clean VM for testing) but most
     users are on Windows, and the test suite should also be run on Windows to
     ensure that it works on that platform as well.  If you
@@ -67,7 +60,7 @@
     ```
 
 00. Test the full-scale regional examples. These examples are big, too
-    large to run on Travis, and will take a lot of time (many hours) to
+    large to run on GitHub Actions, and will take a lot of time (many hours) to
     download and run.
     ```sh
     mkdir tmp-asim
@@ -88,75 +81,48 @@
     There are also demo notebooks for estimation, but their functionality
     is completely tested in the unit tests run previously.
 
-00. Use bump2version to tag the release commit and update the
-    version number.  The following code will generate a "patch" release,
-    incrementing the third value in the version number (i.e. "1.2.3"
-    becomes "1.2.4").  Alternatively, make a "minor" or "major" release.
-    The `--list` command will generate output to your console to confirm
-    that the old and new version numbers are what you expect, before you
-    push the commit (with the changed version in the code) and tags to
-    GitHub.
-    ```sh
-    bump2version patch --list
-    ```
-
-    It is also possible to make a development pre-release. To do so,
-    explicitly set the version number to the next patch plus a ".devN"
-    suffix:
-
-    ```sh
-    bump2version patch --new-version 1.2.3.dev0 --list
-    ```
-
-    Then, when ready to make a "final" release, set the version by
-    explicitly removing the suffix:
+00. Tag the release commit with the new version number.  ActivitySim uses
+    dynamic versioning, so the version number is not stored in a file but
+    is instead read from the most recent git tag, so it is important to tag
+    the repository with the correct version.  The following command will 
+    generate a new tag with the version number "1.2.3" (for example):
     ```sh
-    bump2version patch --new-version 1.2.3 --list
+    git -a v1.2.3 -m "Release v1.2.3"
     ```
 
 00. Push the tagged commit to GitHub.
     ```sh
     git push --tags
     ```
 
-00. For non-development releases, open a pull request to merge the proposed
-    release into main. The following command will open a web browser for
-    you to create the pull request.
-    ```sh
-    gh pr create --web
-    ```
-    After creating the PR, confirm with the ActivitySim PMC that the release
-    is ready before actually merging it.
-
-    Once final approval is granted, merge the PR into main.  The presence
-    of the git tags added earlier will trigger automated build steps to
-    prepare and deploy the release to pypi and conda-forge.
-
-00. Create a "release" on GitHub.
+00. Create a "release" on GitHub.  You can do this from the command line using
+    the `gh` command line tool:
     ```sh
     gh release create v1.2.3
     ```
+    But it may be easier to do this through the 
+    [GitHub web interface](https://github.com/ActivitySim/activitysim/releases/new),
+    where you can select the tag you just created and add a title and description.
+    Both the interactive command line tool shown above and the web interface include
+    the ability to create release notes automatically from the commit messages of
+    all accepted PRs since the last release, but you may want to add additional
+    notes to the release to highlight important changes or new features.
+
     The process of creating and tagging a release will automatically
     trigger various GitHub Actions scripts to build, test, and publish the
     new release to PyPI and conda forge, assuming there are no errors.
 
-    For a development pre-release, include the `--prerelease` argument.
-    As the project's policy is that only formally released code is merged
-    to the main branch, any pre-release should also be built against a
-    non-default branch.  For example, to pre-release from the `develop`
-    branch:
-    ```sh
-    gh release create v1.2.3.dev0 \
-        --prerelease \
-        --target develop \
-        --notes "this pre-release is for a cool new feature" \
-        --title "Development Pre-Release"
-    ```
+00. Build the ActivitySim Standalone Windows Installer.  This is done using 
+    GitHub Actions, but it is not done automatically when a release is created, 
+    instead it requires a manual workflow dispatch trigger.  You can do this by 
+    going to the [build_installer workflow page](https://github.com/ActivitySim/activitysim/actions/workflows/build_installer.yml)
+    and clicking on the "Run workflow" button.  You will need to provide the 
+    version number and choose to add the built installer to the release.
 
 00. Clean up your workspace, including removing the Conda environment used for
     testing (which will prevent you from accidentally using an old
     environment when you should have a fresh up-to-date one next time).
     ```sh
     conda deactivate
-    conda env remove -n TEMP-ASIM-DEV
+    conda env remove -p ./TEMP-ASIM-DEV
     ```