Merge pull request #463 from ActivitySim/develop

publish v1.0.2

.bumpversion.cfg

@@ -0,0 +1,17 @@
+[bumpversion]
+current_version = 1.0.2
+commit = True
+tag = True
+parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(\.(?P<release>.*))?
+serialize = 
+	{major}.{minor}.{patch}.{release}
+	{major}.{minor}.{patch}
+
+[bumpversion:part:release]
+optional_value = final
+first_value = final
+values = 
+	dev
+	final
+
+[bumpversion:file:activitysim/__init__.py]

.travis.yml

@@ -5,68 +5,103 @@ env:
   global:
    # GH_TOKEN ActivitySim/activitysim public_repo token
   - secure: WZeCAmI08hBRgtVWUlerfizvSpOVlBxQDa/Z6HJiDUlIXdSAOIi7TAwnluOgs3lHbSqACegbLCU9CyIQa/ytwmmuwzltkSQN14EcnKea0bXyygd8DFdx4x8st8M3a4nh2svgp4BDM9PCu6T1XIZ1rYM46JsKzNk9X8GpWOVN498=
-  jobs:
-   # Add new TEST_SUITE jobs as needed via Travis build matrix expansion
-  - TEST_SUITE=activitysim/abm/models
-  - TEST_SUITE=activitysim/abm/test
-  - TEST_SUITE=activitysim/cli
-  - TEST_SUITE=activitysim/core
-  - TEST_SUITE=activitysim/estimation/test/test_larch_estimation.py TEST_DEPENDS="larch>=5.5.3 -c conda-forge"
-  - TEST_SUITE=activitysim/examples/example_mtc/test
-  - TEST_SUITE=activitysim/examples/example_multiple_zone/test
-  - TEST_SUITE=activitysim/examples/example_marin/test
-  - TEST_SUITE=activitysim/examples/example_arc/test
-  - TEST_SUITE=activitysim/examples/example_semcog/test
-  - TEST_SUITE=activitysim/examples/example_psrc/test
-  - TEST_SUITE=activitysim/examples/example_sandag/test
+  - TEST_ENV=activitysim-test
+
+jobs:
+  include:
+    # Add new TEST_SUITE jobs as needed via Travis build matrix expansion
+    # define an alternative TEST_ENV to add special dependencies for particular tests
+    # Test suites are arranged in groups; all tests in a group must pass before
+    # the next stage group can begin.
+
+    - stage: Core Functionality
+      env: TEST_SUITE=activitysim/abm/models
+    - env: TEST_SUITE=activitysim/abm/test
+    - env: TEST_SUITE=activitysim/cli
+    - env: TEST_SUITE=activitysim/core
+
+    - stage: Examples
+      name: "MTC Example"
+      env: TEST_SUITE=activitysim/examples/example_mtc/test
+    - name: "Multizone Example"
+      env: TEST_SUITE=activitysim/examples/example_multiple_zone/test
+    - name: "Marin Example"
+      env: TEST_SUITE=activitysim/examples/example_marin/test
+    - name: "ARC Example"
+      env: TEST_SUITE=activitysim/examples/example_arc/test
+    - name: "SEMCOG Example"
+      env: TEST_SUITE=activitysim/examples/example_semcog/test
+    - name: "PSRC Example"
+      env: TEST_SUITE=activitysim/examples/example_psrc/test
+    - name: "SANDAG Example"
+      env: TEST_SUITE=activitysim/examples/example_sandag/test
+
+    - stage: Estimation Mode
+      name: "Larch Test"
+      env: TEST_SUITE=activitysim/estimation/test/test_larch_estimation.py TEST_ENV="activitysim-test-larch"
+
+    - stage: Deployment
+      name: Documentation
+      script:
+        - coveralls
+        # Build docs
+        - mamba install sphinx numpydoc sphinx_rtd_theme
+        - cd docs
+        - make clean
+        - make html
+        - touch _build/html/.nojekyll
+      deploy:
+        - provider: pages
+          local_dir: docs/_build/html
+          skip_cleanup: true
+          github_token: $GH_TOKEN
+          keep_history: true
+          on:
+            branch: master
+    - name: "PyPI Deployment"
+      script: skip     # do not want to rerun any tests
+      deploy:
+        - provider: pypi
+          username: "__token__"
+          password:
+            secure: QeiYRslhBPyDRofmQQDU/7eWEt6OGCbG32HV5c+gxPV41zJY5g3zuIRD5xclyrrFcnSgbHkMSIq3bmhB6oCdA+zemK8TK5GZvCbfs+EtK6/lUbBTXGrRVim7lo2BBFB8p0MwN4HyLMkVdBVm4GVOZug3Coy2yAUTpSy0tREbGJg=
+          skip_existing: true
+          on:
+            branch: [ master ]
 
 python:
-  - '3.7'
-  - '3.8'
+  - '3.9'
 
 install:
-- wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh
-- bash miniconda.sh -b -p $HOME/miniconda
+- wget -O Mambaforge.sh https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-$(uname)-$(uname -m).sh
+- bash Mambaforge.sh -b -p $HOME/miniconda
 - source "$HOME/miniconda/etc/profile.d/conda.sh"
 - hash -r
 - conda config --set always_yes yes --set changeps1 no
-- conda update -q conda
-- conda info -a
-- conda create -q -n test-environment python=$TRAVIS_PYTHON_VERSION
-- conda activate test-environment
-- conda install pytest pytest-cov coveralls pycodestyle $TEST_DEPENDS
-- pip install pytest-regressions
+- mamba update -q mamba
+- mamba info -a
+# write travis python version into selected test environment definition file
+- sed -e "s/\${TRAVIS_PYTHON_VERSION}/${TRAVIS_PYTHON_VERSION}/" conda-environments/${TEST_ENV}.yml > conda-env.yml
+# create test environment in one pass
+- mamba env create -n asimtest --file conda-env.yml
+- conda activate asimtest
 - pip install .
 - pip freeze
 
 script:
+# This is the "default" script used for each test suite, unless overridden with a "script" in the jobs above.
 # build 2 and 3 zone test data twice since the Python test code on Linux sees these as different locations
 - python activitysim/examples/example_multiple_zone/scripts/two_zone_example_data.py
 - python activitysim/examples/example_multiple_zone/scripts/three_zone_example_data.py
-- python /home/travis/miniconda/envs/test-environment/lib/python$TRAVIS_PYTHON_VERSION/site-packages/activitysim/examples/example_multiple_zone/scripts/two_zone_example_data.py
-- python /home/travis/miniconda/envs/test-environment/lib/python$TRAVIS_PYTHON_VERSION/site-packages/activitysim/examples/example_multiple_zone/scripts/three_zone_example_data.py
+- python /home/travis/miniconda/envs/asimtest/lib/python$TRAVIS_PYTHON_VERSION/site-packages/activitysim/examples/example_multiple_zone/scripts/two_zone_example_data.py
+- python /home/travis/miniconda/envs/asimtest/lib/python$TRAVIS_PYTHON_VERSION/site-packages/activitysim/examples/example_multiple_zone/scripts/three_zone_example_data.py
 # pycodestyle
 - pycodestyle activitysim
 # run specific TEST_SUITE job on travis to avoid job max time
 - travis_wait 50 py.test $TEST_SUITE --cov activitysim --cov-report term-missing --durations=0
-
-after_success:
 - coveralls
-# Build docs
-- pip install sphinx numpydoc sphinx_rtd_theme
-- cd docs
-- make clean
-- make html
-- touch _build/html/.nojekyll
 
-deploy:
-  provider: pages
-  local_dir: docs/_build/html
-  skip_cleanup: true
-  github_token: $GH_TOKEN
-  keep_history: true
-  on:
-    branch: master
+
 
 notifications:
   slack:

HOW_TO_RELEASE.md

@@ -0,0 +1,157 @@
+# 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. 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.9 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 master 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
+    and we want to make sure everything passes muster using the 
+    most up-to-date dependencies available.  The following command
+    will update the active environment (we made this to be `TEMP-ASIM-DEV` 
+    if you followed the directions above).
+    ```sh
+    conda env update --file=conda-environments/activitysim-dev.yml
+    ```
+    If you add to the ActivitySim dependencies, make sure to also update 
+    the environments in `conda-environments`, which are used for testing 
+    and development.  If they are not updated, these environments will end 
+    up with dependencies loaded from *pip* instead of *conda-forge*.
+
+00. Run pycodestyle to ensure that the codebase passes all style checks.
+    This check should only take a few seconds.  These checks are also done on
+    Travis and are platform independent, so they should not be necessary to
+    replicate locally, but are listed here for completeness.
+    ```sh
+    pycodestyle .
+    ```
+
+00. Run the regular test suite on Windows. Travis tests are done on Linux,
+    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
+    are not preparing this release on Windows, you should be sure to run
+    at least through this step on a Windows machine before finalizing a 
+    release.  
+
+    A few of the tests require pre-created data that is not included in the 
+    repository directly, but rather recreated on the fly before testing. The 
+    regular test suite takes some time to run, between about half an hour and 
+    two hours depending on the specs of your machine.
+    ```sh
+    python activitysim/examples/example_multiple_zone/scripts/two_zone_example_data.py
+    python activitysim/examples/example_multiple_zone/scripts/three_zone_example_data.py
+    pytest .
+    ```
+
+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 
+    download and run.
+    ```sh
+    mkdir tmp-asim
+    cd activitysim/examples
+    python create_run_all_examples.py > ../../tmp-asim/run_all_examples.bat
+    cd ../../tmp-asim
+    call run_all_examples.bat
+    ```
+    These tests will run through the gamut even if some of them crash, so
+    if you don't sit and watch them go (please don't do this) you'll need 
+    to scan through the results to make sure there are no errors after the
+    fact.
+    ```sh
+    python ../activitysim/examples/scan_examples_for_errors.py .
+    ```
+
+00. Test the notebooks in `activitysim/examples/example_mtc/notebooks`.
+    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:  
+    ```sh
+    bump2version patch --new-version 1.2.3 --list
+    ```
+
+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 master. 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 master.  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.
+    ```sh
+    gh release create v1.2.3
+    ```
+    For a development pre-release, include the `--prerelease` argument.
+    As the project's policy is that only formally released code is merged
+    to the master 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. 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
+    ```

activitysim/__init__.py

@@ -2,5 +2,5 @@
 # See full license in LICENSE.txt.
 
 
-__version__ = '1.0.1'
+__version__ = '1.0.2'
 __doc__ = 'Activity-Based Travel Modeling'