Git 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 three different cloud services for continuous integration (CI). Each service offers unique capabilities, but this also serves to distribute the load.

CircleCI TravisCI AppVeyor

Linux

Linux builds are performed on CircleCI. This CI is configured in {FiPySource}/.circleci/config.yml.

Mac OS X

Mac OS X builds are performed on TravisCI. This CI is configured in {FiPySource}/.travis.yml.

Windows

Windows builds are performed on AppVeyor. This CI is configured in {FiPySource}/.appveyor.yml.

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

Requires PyGithub and Pandas.

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 and place in dist/:

FiPy-x.y.tar.gz

From CircleCI build-binaries Artifacts

~/project/documentation/_build/latex/fipy.pdf

From CircleCI build-36-docs Artifacts

~/project/html.tar.gz

From CircleCI build-36-docs Artifacts

FiPy-x.y.win32.zip

From AppVeyor Artifacts

From the FiPySource directory, unpack dist/html.tar.gz into file:documentation/_build with:

$ tar -xzf dist/html.tar.gz -C documentation/_build

Upload

Attach dist/FiPy-x.y.tar.gz, dist/FiPy-x.y.win32.zip, and documentation/_build/latex/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}.tar.gz

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

Last updated on Jan 14, 2021. Created using Sphinx 3.4.3.