Developer notes

Amara3-xml developer notes

Preparation

You need Github & PyPI update access.

You should also have pypandoc installed, if possible. On Debian-ish systems:

sudo apt-get install pandoc
#pandoc is Python 2.x only, so switch to a py2 VM, then:
pip install pypandoc

Actually at present, until pandoc supports Python 3 we have to generate an RST README by hand and then paste it into setup.py, as discussed below.

Release

#Update README.md
vi README.md
#Generate RST from MD
pandoc -t rst README.md > /tmp/README.rst 
#Next copy the contents of /tmp/README.rst into the LONGDESC constant in setup.py
#Upload to PyPI Test
python setup.py sdist #Then check the contents of dist folder
twine upload dist/* -r testpypi

Now check the updated package page. For example if you're seeing raw RST description rather than HTML, it might be a link whitelist issue. Once it looks all good, proceed to the real release.

First issue a pull request on GitHub to merge develop branch to master. You can do this by

• Make sure you're on Branch: master, then "New pull request"
• You might be able to just use one of the sample PR links provided
• Change the head fork to compare:develop
• Click "Create pull request", fill the form & address any conflicts
• Click "Merge pull request" then "Confirm merge"
• Do not delete the develop branch

Then back on cmdline:

#Switch to master
git checkout master
git pull

#Upload to PyPI
python setup.py sdist #Then check the contents of dist folder
twine upload dist/*

Use GitHub to prepare a release

Finally switch back to develop branch

git checkout develop
#Bump version for next release
vi lib/version.py
git commit -am "Bump version"

One-time step per developer: Preparation for pushing to PyPI

Also use testpypi and so have set up index-servers in ~/.pypirc

[distutils]
index-servers=
    pypi
    testpypi

[pypi]
username = <your user name goes here>
password = <your live password optionally goes here>

[testpypi]
repository = https://testpypi.python.org/pypi
username = <your user name goes here>
password = <your test password goes here>

Obsolete release tagging steps

#Select tag name, update according to released version
#Tag release
export RELEASETAG=v3.0.0b5
git tag -a $RELEASETAG -m "Release of version $RELEASETAG" #Must be double, not single quotes
#Push the tag to Github
git push origin $RELEASETAG
#Hmm how about git push --tags origin master ?

Note: if you make a mistake tagging you can undo it using:

git tag -d $RELEASETAG
git push origin ":refs/tags/$RELEASETAG"