create admin.rst; universal wheel

.github/workflows/release.yml

@@ -66,8 +66,8 @@ jobs:
     strategy:
       max-parallel: 2
       matrix:
-        os: [ macos-latest, windows-latest ]
-        python-version: [ 3.7, 3.8 ]
+        os: [ macos-latest ]
+        python-version: [ 3.7 ]
     runs-on: ${{ matrix.os }}
 
     steps:

ADMIN.rst

@@ -0,0 +1,113 @@
+Introduction
+============
+
+This documentation provides a guide for mdgo administrators. The following
+assumes you are using miniconda or Anaconda.
+
+Releases
+========
+
+The general procedure to releasing mdgo 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.
+
+Initial setup
+-------------
+
+Install some conda tools first::
+
+	conda install --yes conda-build anaconda-client
+	conda config --add channels matsci
+
+Mdgo uses `invoke <http://www.pyinvoke.org/>`_ to automate releases. You will
+also need sphinx. Install these using::
+
+	pip install --upgrade invoke sphinx
+
+For 2018, we will release both py27 and py37 versions of mdgo. Create
+environments for py37 using conda::
+
+	conda create --yes -n py37 python=3.7
+
+For each env, install required packages followed by dev install for
+mdgo::
+
+	conda activate py37
+	pip install -r requirements.txt
+	pip install -r requirements-optional.txt
+	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:
+
+* It can be useful to `pip install --upgrade pip twine setuptools` (this may
+  be necessary if there are authentication errors when connecting to PyPI).
+
+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::
+
+    conda activate 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 --nodoc
+    invoke update-doc
+    conda deactivate
+    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 mdgo.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 <https://github.com/materialsvirtuallab/materials.sh>`_.
+This repo contains the conda skeletons to build the conda versions for various
+matsci codes on the Anaconda `matsci channel <https://anaconda.org/matsci>`_.
+
+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 mdgo meta.yaml::
+
+	invoke update-pypi mdgo
+
+Build the mac versions manually::
+
+	invoke build-conda mdgo
+
+Commit and push to repo, which will build the Linux and Windows versions.
+
+Check that the `matsci channel <https://anaconda.org/matsci>`_ versions are
+properly updated.