.. _rel-spack:

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

This assumes you have already:

 - made a PyPI package for new version of libEnsemble 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/questions/6286571/are-git-forks-actually-git-clones.

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

If you have local changes to go "on top" of latest code::

    git rebase upstream/develop

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

    git reset --hard upstream/develop

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

    git push origin develop --force

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

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](https://spack.readthedocs.io/en/latest/packaging_guide.html) and
[contribution](https://spack.readthedocs.io/en/latest/contribution_guide.html) guides for more info.

Quick example to update libEnsemble::

    git branch update_libensemble
    git checkout 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 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 flake8

If okay add, commit, and push to origin (forked repo)::

     git commit -am "Update libensemble"
     git push origin update_libensemble --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 develop branch on 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>
