ADMIN.rst

Introduction

This docmentation provides a guide for pymatgen administrators. The following assumes you are using miniconda or Anaconda.

Releases

The general procedure to releasing pymatgen comprises the following steps:

1. Wait for all unittests to pass on CircleCI.
2. Update and edit change log.
3. Release PyPI versions + doc.
4. Release conda versions.
5. Release Dash documentation.

Initial setup

Install some conda tools first:

conda install --yes conda-build anaconda-client
conda config --add channels matsci

Pymatgen uses invoke to automate releases. You will also need sphinx and doc2dash. Install these using:

pip install --upgrade invoke sphinx doc2dash

For 2018, we will release both py27 and py37 versions of pymatgen. Create environments for py27 and py37 using conda:

conda create --yes -n py37 python=3.7
conda create --yes -n py27 python=2.7

For each env, install some packages using conda followed by dev install for pymatgen:

conda activate py37
conda install --yes numpy scipy sympy matplotlib cython
pip install -r requirements.txt
pip install -r requirements-optional.txt
pip install invoke sphinx doc2dash
python setup.py develop
conda activate py27
conda install --yes numpy scipy sympy matplotlib cython
pip install -r requirements.txt
pip install -r requirements-optional.txt
pip install invoke sphinx doc2dash
python setup.py develop

Add your PyPI username and password and GITHUB_RELEASE_TOKEN into your environment:

export TWINE_USERNAME=PYPIUSERNAME
export TWINE_PASSWORD=PYPIPASSWORD
export GITHUB_RELEASES_TOKEN=TOKEN_YOU_GET_FROM_GITHUB

You may want to add these to your .bash_profile to avoid having to type these each time.

Machine-specific issues

The above instructions are general, but there are some known issues that are machine-specific:

• Installing lxml via pip required STATIC_DEPS=true pip install lxml on macOS 10.13.
• It can be useful to pip install --upgrade pip twine setuptools (this may be necessary if there are authentication errors when connecting to PyPI).
• You may have to brew install hdf5 netcdf or similar to be able to pip install the optional requirement netCDF4.

Doing the release

First update the change log. The autogenerated change log is simply a list of commit messages since the last version. Make sure to edit the log for brevity and to attribute significant features to appropriate developers:

conda activiate py37
invoke update-changelog

Then, do the release with the following sequence of commands (you can put them in a bash script in your PATH somewhere):

conda activate py37
invoke release --notest --nodoc --logdir="~/Desktop/"
conda deactivate
conda activate py27
python setup.py bdist_wheel
twine upload dist/*p27*
# You may wonder why update-doc is done with py27. The reason is because there
# are py37 incompatibilities with some of doc2dash dependencies (lxml). We
# will go back to using py37 by default in future.
invoke update-doc
conda deactivate
python setup.py develop

(Where logdir is a directory of your choice.)

Double check that the releases are properly done on Pypi. If you are releasing on a Mac, you should see a pymatgen.version.tar.gz and two wheels (Py37 and Py27). There will be a py37 wheel for Windows that is generated by Appveyor.

Materials.sh

Fork and clone the materials.sh. This repo contains the conda skeletons to build the conda versions for various matsci codes on the Anaconda matsci channel.

The first time this is run, you may need to pip install beautifulsoup4.

If you doing this for the first time, make sure conda-build and anaconda-client are installed:

conda install --yes conda-build anaconda-client

Update the pymatgen meta.yaml:

invoke update-pypi pymatgen

Build the mac versions manually:

invoke build-conda pymatgen

Commit and push to repo, which will build the Linux and Windows versions.

Check that the matsci channel versions are properly updated.

Dash docs

Fork and clone the Dash User Contributions repo.

Generate the offline Dash doc using:

invoke contribute-dash

Create a pull request and submit.