Development

This page contains standard practices for developing Amp, focusing on repositories and documentation.

Official repository

The official Amp repository lives on bitbucket, andrewpeterson/amp . We employ a branching model where the master branch is the main development branch, containing day-to-day commits from the core developers and honoring merge requests from others. From time to time, we create a new branch that corresponds to a release. This release branch contains only the tagged release and any bug fixes.

Contributing

You are welcome to contribute new features, bug fixes, better documentation, etc., to Amp. If you would like to contribute, please create a private fork and a branch for your new commits. When it is ready, send us a merge request. We follow the same basic model as ASE. Please see the ASE documentation for complete instructions; a summary is also listed below.

As good coding practice, make sure your code passes both the pyflakes and pep8 tests. (On linux, you should be able to run pyflakes file.py and pep8 file.py; then correct your code until the warnings disappear.) If adding a new feature: please add a (very brief) test to the tests folder to ensure your new code continues to work as the project evolves, and also be sure to write clear documentation. Finally, to make users aware of your new feature or change, add a bullet point to the release notes page of the documentation under the Development version heading.

It is also a good idea to send us an email if you are planning something complicated.

Your fork and branches

If you would like to contribute, here is our recommended way of using git to ultimately create a merge request that contains all of your changes to be included in Amp.

Initial setup. First, create an account on bitbucket, and from the official Amp repository click the button to create a fork into your own account. From the website for your fork, find the button to clone it, and use this to create a copy on your own filesystem. This means you will run a command similar to this on your own machine:

git clone git@bitbucket.org:myusername/amp.git

On your local computer, the term “origin” will refer to your own fork of Amp; we will also need to be able to access the original fork; we’ll name this “upstream” and link it with a command like:

git remote add upstream git@bitbucket.org:andrewpeterson/amp.git

You can check that the above makes sense by running git remote -v.

Making changes. Before making any changes, it’s a good idea to make sure your local copy is up-to-date with the parent fork. You can do this with

git checkout master  # Make sure we are on the right branch.
git pull upstream master

To make changes, first create a local branch with a descriptive name, for example “fix-fingerprints”. You can do this with

git checkout -b fix-fingerprints

Your local code is now in a new branch, which you can verify by typing git status (or git branch to see all your branches). Now, go ahead and edit your code and commit your changes with git commit. You can make as many commits to your local copy as you like as you develop. When you think your code is ready to be part of the official Amp repository, first make sure it is still up-to-date with the upstream repository, then push your branch to your own fork:

git pull upstream master
git push origin fix-fingerprints

Now you are ready to put in a merge request. You will likely see a local message telling you how to do this after you push, but if not, just go to your own bitbucket page, open the branch there, and look for a button for a merge request. Type a clear description and submit.

If you’d like to discuss some aspects of your code before it is ready, you can do the above but prefix the merge request title with “WIP: ” (work in progress). Then others can review your code before you submit it officially.

Documentation

This documentation is built with sphinx. (Mkdocs doesn’t seem to support autodocumentation.) To build a local copy, cd into the docs directory and try a command such as

sphinx-build . /tmp/ampdocs
firefox /tmp/ampdocs/index.html &  # View the local copy.

This uses the style “bizstyle”; if you find this is missing on your system, you can likely install it with

pip install --user sphinxjp.themes.bizstyle

You should then be able to update the documentation rst files and see changes on your own machine. For line breaks, please use the style of containing each sentence on a new line.

Releases

To create a release, we go through the following steps.

  • Reserve a DOI for the new release via zenodo.org. Do this by creating a new upload, and choosing “pre-reserve” before adding any files.

  • Prepare the master branch for the release. (1) Update Release Notes, where the changes should have been catalogued under a “Development version” heading; move these to a new heading for this release, along with a release date and the DOI from above. (2) Also note the latest stable release on the index.rst page.

  • Create a new branch on the bitbucket repository with the version name, as in v0.5. (Don’t create a separate branch if this is a bugfix release, e.g., 0.5.1 — just add those to the v0.5 branch.) Note the branch name starts with “v”, while the tag names will not, to avoid naming conflicts.

  • Check out the new branch to your local machine (e.g., git fetch && git checkout v0.5). All subsequent work is in the new branch.

  • Change amp/VERSION to reflect the release number (without ‘beta’). Note this will automatically change it in docs/conf.py, the Amp log files, and setup.py.

  • On the Release Notes page, delete the “Development version” heading.

  • Commit and push the changes to the new branch on bitbucket.

  • Tag the release with the release number, e.g., ‘0.5’ or ‘0.5.1’, the latter being for bug fixes. Do this on a local machine (on the correct branch) with git tag -a 0.5, followed by git push origin –tags.

  • Add the version to readthedocs’ available versions; also set it as the default stable version. (This may already be done automatically.)

  • Upload an archive and finalize the DOI via zenodo.org. Note that all the “.git” files and folders should be removed from the .tar.gz archive before uploading to Zenodo.

  • Prepare and upload to PyPI (for pip):

    $ python3 setup.py sdist
    $ twine upload dist/*
    
  • Send a note to the amp-users list summarizing the release.

  • In the master branch, update the VERSION file to reflect the new beta version.