=========================
Making a Mathics3 Release
=========================

This information is for Project administrators. It is likely to be of
little interest for most.

To perform these steps, this you'll need a project administrator
accounts and access on github, PyPI and dockerhub.


Beforehand
==========

Let folks know in advance about the release. During the release of
course, ensure no one is changing master (except the person doing the
release).

mathics-scanner may need to be released on PyPI first.

Get latest sources:
===================

::

    $ git pull

Change version in mathics/version.py
====================================

On Mathics3/mathics-core master branch. For each release candidate:

update ``__version__`` in ``mathics/version.py``

::

    $ source mathics/version.py # to set in POSIX shell
    $ echo $__version__
    $ git commit -m"Get ready for release $__version__" .

Create a new branch
===================

::
    git checkout -b release-$__version__

Update Changes
==============

::

    $ make ChangeLog

Update ``CHANGES.rst`` from ``ChangeLog``

::

    $ make check
    $ git commit --amend .
    $ git push   # get CI testing going early

Build Docs
==========

::

    $ make doc

See also [[Documentation and tests]].

Check package from github
=========================

TODO: turn this into a script in ``admin-tools``

::

    $ [[ ! -d /tmp/gittest ]] && mkdir /tmp/gittest; pushd /tmp/gittest
    $ pyenv local pyston-2.3.4 # Use a version that is not the most recent
    $ pip install -e git+https://github.com/Mathics3/mathics-core.git#egg=Mathics3
    $ (cd src/mathics3 && make)
    $ mathics --version # see that new version appears
    $ mathics -e "1+2"
    $ python -m pip uninstall Mathics3
    $ popd

Make packages and check
=======================

::

    $ ./admin-tools/make-dist.sh
    $ twine check dist/Mathics3-$__version__*

Release on Github
=================

Go to https://github.com/Mathics3/Mathics-core/releases/new

https://cloudconvert.com/rst-to-md can be used to change the CHANGES.rst
section to markdown.

Now check the *tagged* release. (Checking the untagged release was
previously done).

TODO: turn this into a script in ``admin-tools``

::

    $ git pull # to pull down new tag
    $ pushd /tmp/gittest
    $ pip install -e git+https://github.com/Mathics3/mathics-core.git@${__version__}#egg=Mathics3
    $ mathics --version
    $ mathics -e "1+2"
    $ pip uninstall Mathics3
    $ popd

Upload the release to PyPI
==========================

Upload it to PyPI with ``twine``:

.. code:: bash

    $ twine upload --verbose dist/Mathics3-${__version__}*

Post-Release
============

* Update mathicsscript
* Update Matthics-Django
* Update mathics-omnibus

Update magic.github.io PDF
--------------------------

::

       $ cp mathics/doc/tex/mathics.pdf ../mathics.github.io/docs/mathics-${__version__}.pdf
       $ cd ../mathics.github.io/docs
       $ git add mathics-${__version__}.pdf
       $ rm mathics-latest.pdf
       $ ln -vs mathics-${__version__}.pdf mathics-latest.pdf
       $ git commit .
       $ git push

-  Announce release on Google-Groups pages
-  https://groups.google.com/forum/#!forum/mathics-devel,
-  https://groups.google.com/forum/#!forum/mathics-users, and
-  https://groups.google.com/g/sage-develsage-users
-  Update ``__version__`` to ``NEXT_VERSION.dev0``