Skip to content

Latest commit

 

History

History
151 lines (109 loc) · 3.87 KB

ADMIN.md

File metadata and controls

151 lines (109 loc) · 3.87 KB
Raw

Introduction

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

Releases

The general procedure for releasing pymatgen comprises the following steps:

  1. Make sure all CI checks are green. We don't want to release known bugs.
  2. Update and edit changelog.
  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

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

pip install --upgrade invoke sphinx doc2dash

Create environment for py38 using conda:

conda create --yes -n py38 python=3.8

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

conda install --yes numpy scipy sympy matplotlib cython
pip install '.[optional]'
pip install invoke sphinx doc2dash

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

Ensure appropriate environment variables are set including DISCOURSE_API_USERNAME, DISCOURSE_API_KEY and GITHUB_RELEASES_TOKEN.

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:

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):

invoke release --notest --nodoc
invoke update-doc
python setup.py develop

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 P). 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.