.. _rel-spack:

A workflow for updating libEnsemble on Spack
============================================

This assumes you have already:

 - made a PyPI package for the new libEnsemble version and
 - made a GitHub fork of Spack and cloned it to your local system.

Details on how to create forks can be found at https://help.github.com/articles/fork-a-repo.

You now have a configuration like that shown at https://stackoverflow.com/a/6286877/6346040.

Upstream, in this case, is the official Spack repository on GitHub. Origin is
your fork on GitHub, and Local Machine is your local clone (from your fork).

Make sure ``SPACK_ROOT`` is set and Spack binary is in your path::

    export SPACK_ROOT=<PATH/TO/LOCAL/SPACK/REPO>
    export PATH=$SPACK_ROOT/bin:$PATH

Do ONCE in your local checkout:

To set upstream repo::

    git remote add upstream https://github.com/spack/spack.git
    git remote -v # check added

(Optional) To prevent accidental pushes to upstream::

    git remote set-url --push upstream no_push
    git remote -v # Check for line: `upstream no_push (push)`

Updating (the develop branch)
----------------------------------

You will now update your local machine from the upstream repo (if in doubt,
make a copy of the local repo in your file system before doing the following).

Check that the upstream remote is present::

    git remote -v

Ensure that you are on the develop branch::

    git checkout develop

Fetch from the upstream repo::

    git fetch upstream

To update your local machine, you may wish to rebase or overwrite your local files.
Select from the following:

Now make your local machine identical to the upstream repo (**WARNING:** Any local changes will be lost!)::

    git reset --hard upstream/develop

Alternatively, if you have existing local changes to go "on top" of the latest
code (usually we will make our release updates after this)::

    git rebase upstream/develop

(Optional) You may want to update your forked (origin) repo on GitHub at this point.
This may require a forced push::

    git push origin develop --force

Making changes
--------------

The instructions below assume you make changes on the default develop branch.
You can optionally create a branch to make changes on. Doing so may be a good
idea, especially if you have multiple packages, to make separate branches for
each package.

See the Spack packaging_ and contribution_ guides for more info.

Quick example to update libEnsemble
-----------------------------------

This will open the libEnsemble ``package.py`` file in your editor (given by
environment variable ``EDITOR``)::

    spack edit py-libensemble  # SPACK_ROOT must be set (see above) (Python packages use "py-" prefix)

Or just open it manually: ``var/spack/repos/builtin/packages/py-libensemble/package.py``.

Now get the checksum for new lines:

Get the tarball (see PyPI instructions), for the new release and use::

    sha256sum libensemble-*.tar.gz

Update the ``package.py`` file by pasting in the new checksum lines (and make
sure the URL line points to the latest version). Also update any dependencies
for the new version.

Check package::

     spack style

This will install a few Python Spack packages and run style checks on just
your changes. Make adjustments if needed, until this passes.

If okay - add, commit, and push to origin (forked repo). For example, if your version
number is 1.2.2::

     git commit -am "libEnsemble: add v1.2.2"
     git push origin develop --force

Once the branch is pushed to the forked repo, go to GitHub and do a pull request from this
branch on the fork to the develop branch on the upstream.

Express Summary: Make Fork Identical to Upstream
------------------------------------------------

Quick summary for bringing the develop branch on a forked repo up to speed with upstream
(YOU WILL LOSE ANY CHANGES)::

    git remote add upstream https://github.com/spack/spack.git
    git fetch upstream
    git checkout develop
    git reset --hard upstream/develop
    git push origin develop --force

Reference: <https://stackoverflow.com/questions/9646167/clean-up-a-fork-and-restart-it-from-the-upstream/39628366>

.. _packaging: https://spack.readthedocs.io/en/latest/packaging_guide.html
.. _contribution: https://spack.readthedocs.io/en/latest/contribution_guide.html