Versioning

• For a long time after switching to git, we relied on shortened git hashes for versioning. These are great for specificity but useless for ordering. The following scheme has been accepted for versioning henceforth. It derives an orderable version number from the git hash. Some references on versioning:

  • http://semver.org/
  • https://www.python.org/dev/peps/pep-0440/
  • https://www.python.org/dev/peps/pep-0386/

• MAJOR.minor.patch as interpreted for psi4

  • MAJOR currently = 0, convert from beta = 1, next paper = 2
  • minor increment by making a tag (see below) of MAJOR.minor at any commit of medium or higher import
  • patch bug fixes or minor contributions, auto-incremented at each commit

• conda-build uses tags and git describe --tags results to form a version label uniting an orderable version number and git hashes.

---

###How to decide upon and make a version bump

Whenever you make a commit of moderate import (such that you might want to tell someone to get version x.x or higher for a feature), make a tag for that commit.

• See existing tags with describe or at https://github.com/psi4/psi4/tags

git describe 0.14

make two commits beyond tag

git describe 0.14-2-g24242c3 ```

• Use annotated tags. Don't put the "v" for version only label. MAJOR.minor ONLY! Note that creating a release through the GitHub interface only uses lightweight tags not annotated tags.

git tag -a 0.15 -m 'now with ECPs' ```

• Tags don't get pushed along with commits. You'll have to push them yourself.

git push origin [tagname] ```

---

###How to get and interpret the version number

• from a Psi4 executable:

psi4 --version 0.2.83

* from an output file:

-----------------------------------------------------------------------
      Psi4: An Open-Source Ab Initio Electronic Structure Package
                          Psi4 0.1.83 Driver

                      Git: Rev {master} 20ba238

* from a conda package file ``linux-64/psi4-0.2.83-py27_g20ba238.tar.bz2`` as stored at https://anaconda.org/psi4/psi4/files

* interpretation
* ``psi4`` is project name
* ``0.2`` is latest tag
* ``83`` is number of commits since latest tag
* ``py27`` built with python 2.7
* ``g`` git repository, not mercurial, etc.
* ``20ba238`` is the shortened git hash
 
---
###<a name="writepsi4"></a>How to refer to Psi4

Ways to refer to Psi4 in text, in order of decreasing goodness:

* as ``Psi4`` in Optima regular font with "si" in custom small caps according to [logo info](../blob/master/media/logos/INFO.txt).
* as ``Psi4`` with "si" in generated small caps
  * html: ``<span style="font-family: Optima, sans-serif; color: #273896;">P<span style="font-size: 82%;">SI</span>4</span>``
  * html: ``<span style="font-variant: small-caps;">Psi4</span>``
* as ``Psi4`` with "si" in lowercase
* as ``psi4`` in code
* **NOT** ``PSI4`` or ``PSI``