FiPyGit practices¶
Refer to Git usage for the current branching conventions.
Branches¶
Whether fixing a bug or adding a feature, all work on FiPy should be conducted on a branch and submitted as a pull request. If there is already a reported GitHub issue, name the branch accordingly:
$ BRANCH=issue12345-Summary_of_what_branch_addresses
$ git checkout -b $BRANCH master
Edit and add to branch:
$ emacs ...
$ git commit -m "refactoring_stage_A"
$ emacs ...
$ git commit -m "refactoring_stage_B"
Merging changes from master to the branch¶
Make sure master is up to date:
$ git fetch origin
Merge updated state of master to the branch:
$ git diff origin/master
$ git merge origin/master
Resolve any conflicts and test:
$ python setup.py test
Submit branch for code review¶
If necessary, fork the fipy repository.
Add a “remote” link to your fork:
$ git remote add <MYFORK> <MYFORKURL>
Push the code to your fork on GitHub:
$ git push <MYFORK> $BRANCH
Now create a pull request from your $BRANCH against the master
branch of usnistgov/fipy. The pull request should initiate
automated testing. Check the Continuous Integration status. Fix (or,
if absolutely necessary, document) any failures.
Note
If your branch is still in an experimental state, but you would like to
check its impact on the tests, you may prepend “WIP:” to your pull
request title. This will prevent your branch from being merged before
it’s complete, but will allow the automated tests to run.
Please be respectful of the Continuous Integration resources and do the bulk of your testing on your local machine or against your own Continuous Integration accounts (if you have a lot of testing to do, before you create a pull request, push your branch to your own fork and enable the Continuous Integration services there.
You can avoid testing individual commits by adding “[skip ci]” to the
commit message title.
When your pull request is ready and successfully passes the tests, you can request a pull request review or send a message to the mailing list about it if you like, but the FiPy developers should automatically see the pull request and respond to it without further action on your part.
Refactoring complete: merge branch to master¶
Attention
Administrators Only!
Use the GitHub interface to merge the pull request.
Note
Particularly for branches with a long development history, consider doing a Squash and merge.
Continuous Integration¶
We use the Azure and GitHub Actions cloud services for
Continuous Integration (CI). These CIs are configured in
FiPySource/.azure/pipelines.yml, FiPySource/.github/workflows/NISTtheDocs2Death.yml, and
FiPySource/.github/workflows/nix.yml.
Note
In order to focus on breakages introduced by changes to FiPy, a
pull request is normally built with one of the Conda Lockfiles,
whereas the nightly builds use an environment.yml in order to
catch breakages introduced by FiPy’s prerequisites.
A pull request may be tested with the latest prerequisites by setting
the CONDA_ENVIRONMENT_NOT_LOCK environment variable in
Azure at queue time.
Conda Lockfiles¶
The conda-lock lockfiles in
environments/locks/ can be updated with:
$ for solver in petsc pysparse scipy trilinos
do
conda-lock lock \
--file environments/${solver}-environment.yml \
--lockfile environments/locks/conda-${solver}-lock.yml
conda-lock render \
--filename-template environments/locks/conda-${solver}-{platform}.lock \
environments/locks/conda-${solver}-lock.yml
done
Attention
Do not merge new lockfiles to master without validating that
everything still works.
Making a Release¶
Attention
Administrators Only!
Source¶
Make sure master is ready for release:
$ git checkout master
Check the issue list and update the Change Log:
$ git commit CHANGELOG.txt -m "REL: update new features for release"
Note
You can use:
$ python setup.py changelog --after=<x.y>
or:
$ python setup.py changelog --milestone=<x.z>
to obtain a ReST-formatted list of every GitHub pull request and issue closed since the last release.
Particularly for major and feature releases, be sure to curate the
output so that it’s clear what’s a big deal about this release.
Sometimes a pull request will be redundant to an issue, e.g.,
“Issue123 blah blah”. If the pull request fixes a bug,
preference is given to the corresponding issue under Fixes.
Alternatively, if the pull request adds a new feature, preference is
given to the item under Pulls and corresponding issue should be
removed from Fixes. If appropriate, be sure to move the “Thanks to
@mention” to the appropriate issue to recognize outside contributors.
Attention
If Continuous Integration doesn’t show all green boxes for this
release, make sure to add appropriate notes in README.txt or
INSTALLATION.txt!
Release from master¶
$ git checkout master
Resolve any conflicts and tag the release as appropriate (see Git practices above):
$ git tag --annotate x.y master
Push the tag to GitHub:
$ git push --tags origin master
Upon successful completion of the Continuous Integration systems, fetch
the tagged build products from Azure Artifacts and place in
FiPySource/dist/:
dist-Linux/FiPy-x.y-none-any.whl
dist-Linux/FiPy-x.y.tar.gz
dist-Windows_NT/FiPy-x.y.zip
dist-docs/FiPy-x.y.pdf
dist-docs/html-x.y.tar.gz
From the FiPySource directory, unpack dist/html-x.y.tar.gz
into docs/build with:
$ tar -xzf dist/html-{x.y}.tar.gz -C docs/build
Upload¶
- Attach
dist/FiPy-x.y-none-any.whldist/FiPy-x.y.tar.gzdist/FiPy-x.y.zipdist/FiPy-x.y.pdf
to a GitHub release associated with tag x.y.
Upload the build products to PyPI with twine:
$ twine upload dist/FiPy-${FIPY_VERSION}.*
Upload the web site to CTCMS
$ export FIPY_WWWHOST=bunter:/u/WWW/wd15/fipy
$ export FIPY_WWWACTIVATE=updatewww
$ python setup.py upload_products --html
Warning
Some versions of rsync on Mac OS X have caused problems
when they try to upload erroneous \rsrc directories. Version 2.6.2
does not have this problem.
Update conda-forge feedstock¶
Once you push the tag to GitHub, the fipy-feedstock should automatically receive a pull request. Review and amend this pull request as necessary and ask the feedstock maintainers to merge it.
This automated process only runs once an hour, so if you don’t wish to wait (or it doesn’t trigger for some reason), you can manually generate a pull request to update the fipy-feedstock with:
revised version number
revised sha256 (use
openssl dgst -sha256 /path/to/fipy-x.y.tar.gz)reset build number to
0
Announce¶
Make an announcement to fipy@list.nist.gov