Fissa

Push the branch to the repository and go to the [repository page][our repo] to create a pull request into the master branch.
sh
git push -u origin $(git symbolic-ref --short HEAD)
sensible-browser "https://github.com/rochefort-lab/fissa/compare/$(git symbolic-ref --short HEAD)?expand=1&labels=doc&title=DOC:%20Add%20${vMNP}%20to%20CHANGELOG&body=Adds%20new%20release%20${vMNP}%20to%20the%20CHANGELOG."


The title of the PR should be `DOC: Add vM.N.P to CHANGELOG`.

Once you've created the PR, double-check that the only changed files are `CHANGELOG` and (possibly) `__meta__.py`.
If they are, once the continuous integration tests have passed, you can merge the PR into master.
If there are more changes beyond this, your PR needs further review.


[our repo]: http://github.com/rochefort-lab/fissa/
[numpy release]: https://github.com/numpy/numpy/blob/master/doc/HOWTO_RELEASE.rst.txt
[semver]: https://semver.org/spec/v2.0.0.html
[PEP440]: https://www.python.org/dev/peps/pep-0440
[Keep a Changelog]: https://keepachangelog.com

Check the [current version number on the master branch](https://github.com/rochefort-lab/fissa/blob/master/fissa/__meta__.py).

If you have released a new major/minor version with a version number higher than this, you need to update the version on the master branch to be `M.N.dev0`.

If you have released a patch, or the master branch otherwise already has the correct version number, just make sure your version number in `__meta__.py` matches that of master (check with `less fissa/__meta__.py`).

Edit the `__meta__.py` file
sh
gedit fissa/__meta__.py

to be `A.B.dev0`, where `A.B` is the latest minor version.

Once you've edited the `__meta__.py` file, commit this change (replacing the placeholder text `A.B.dev0` with the actual current minor version in this example code).
sh
git add fissa/__meta__.py
git commit -m "REL: Change bleeding-edge version number to A.B.dev0"

Our unstable version on the master branch should always contain a CHANGELOG entry which compares the last stable release with the current unstable version.

Edit the CHANGELOG
sh
gedit CHANGELOG.rst

to include an entry at the top of the list of entries, which reads as follows:

Unreleased
----------

`Full commit changelog <https://github.com/rochefort-lab/fissa/compare/A.B.C...master>`__.


where `A.B.C >= M.N.P` is the latest release, including your forthcoming `M.N.P` release.

Commit this change.
sh
git add CHANGELOG.rst
git commit -m "DOC: Add Unreleased section to CHANGELOG"

If your release does not have the highest version number (because it is a patch for an older release), you should do the following:
sh
git fetch
git checkout master
git checkout -b "doc_changelog-$MNP"
git cherry-pick "origin/rel_$MNP"


This will take the last commit from your release-candidate branch, and add it to the commit history.
If you have followed this guide, the last commit will be the CHANGELOG update.
You will have to handle a merge conflict resulting from the cherry-pick.

Afterwards, you can double-check which commits were included with `git log`, or an interactive rebase `git rebase -i master`.

If your new release has the highest version number, you should do this on your `rel_M.N.P` branch.

First, update the `rel_M.N.P` to contain the release itself, contained in branch `vM.N.x`.
sh
git fetch
git checkout "rel_$MNP"
git merge "origin/v$MNx"


If you've followed the steps in this guide in the order they are given, when you perform the `git fetch` step you should receive a new tag called `M.N.P` from the origin remote.
The merge into `rel_M.N.P` will be done with the fast forward method, adding one merge commit from the PR to its history.

Now proceed to step 10.2.

For the body of the release, we will use your entry in the CHANGELOG, including subheadings such as `Added`, `Fixed`, etc.

However, you will need to convert the formatting from RST to Markdown.
The full changelog can be converted using this command:
sh
pandoc --from rst --to markdown+hard_line_breaks CHANGELOG.rst | sed '/^:::/d' > .CHANGELOG.md

From the converted document, you can select the relevant section to include in the github release body.

If you make a formatting mistake and realise after publishing the release on GitHub, don't worry as the release metadata can be editted.

When you are done, delete the temporary file generated by pandoc.
sh
rm .CHANGELOG.md


9. Push to PyPI

You will need to be a maintainer of this project in order to push a new version.

**Note that this step is irreversible.**
If you push the wrong thing here, you can't overwrite it.
sh
python -m pip install --upgrade setuptools wheel twine
python -m twine upload dist/*

You will be prompted for your username and password, which must be associated with a maintainer for the project.

Try out the PyPI release

You'll first need to wait a couple of minutes for the new PyPI version to become available.

Again, we create a fresh virtual environment and install the new release into it.
sh
REPODIR="$(pwd)"
cd ~
rm -rf pypi_test_env
virtualenv -p /usr/bin/python3 pypi_test_env
source pypi_test_env/bin/activate
python -m pip install fissa
python -c "import fissa; print(fissa.__version__)"


You should confirm that the version number outputted matches the version of your new release.

We now remove the temporary environment and return to the repository.
sh
deactivate
rm -rf pypi_test_env
cd "$REPODIR"


10. Update metadata on the master branch

You need to merge the updated CHANGELOG into the master branch.
There are two procedures for doing this, depending on whether your new release has the highest version number, or if it was a patch release for an older version.