Skip to content

Notes for code maintainers (making a release, merging from up stream, ...)

Jump to bottom
Giovanni Pizzi edited this page Feb 15, 2024 · 2 revisions

How to make a new release

Preliminary steps

  • Update various files (see e.g. #311 for v3.1, with minor changes in #316), including:
    • Release number (in the code, in the docs and tutorial, ...)
    • Changelog
    • Contributors, in:
      • Code header
      • User guide (overview file, Credits section)
      • README.rst
      • wannier.org website
    • Make sure that all files have the correct header (e.g. if a new file is added)
    • The Makefile to produce a tar.gz with the correct name (or simply use the files generated by GitHub when tagging?)
  • Check on the test farm if all compilers work
  • Recompile docs and add/commit the final pdf into doc/compiled_doc replacing old versions (do it only when you are sure the PDF is final, to avoid the increase of the repository size with too many PDFs).
  • If Quantum ESPRESSO has made a new release, make sure the post-X.Y folder is updated to the appropriate release, synchronise the file from/to the Quantum ESPRESSO main code on GitLab.
  • Recompile the FORD docs (folder autodoc)

Finally:

  • make the final PR on master

  • Create a tag with format vX.Y or vX.Y.Z on the latest master commit (after merging the PR) via

    git tag vX.Y.Z

This will tag the latest commit. Run git tag -l to check that the new tag follows the same syntax of the other ones, and that there are no spurious tags.

  • Push the tags to the official repository:

    git push --tags

  • Create a new release on the GitHub interface, using the just-created git tag.

  • Merge master into develop (via an intermediate temporary branch)

  • Fix the website

    • Add news
    • possibly update features of the code
    • download page (version and date of the most recent release, and link at the bottom of the previous releases)
    • support page (link to newer documentation PDFs)
    • add FORD docs (via SSH)
    • update the 'History' page

  • Send a notification to the mailing list

How to merge the most recent work on the official repository into my fork

To be done only once

  • Clone your fork
  • Run the following command to reference the official repository as "upstream":

git remote add upstream https://github.com/wannier-developers/wannier90.git

Every time you want to merge

  • first commit all your changes (and if you want, also push them to your repository)
  • then, run git pull upstream develop to merge all "official" changes in your branch

Merge behaviour (and merge conflicts)

At this stage, three different things can happen:

  • Changes have happened only on different files. Then they are ported into your branch, you can continue to work happily.
  • Changes have also happened to files you edited, but git could merge without problems. It will ask you then to store a message for a commit that represents the merge, you can simply accept the default message.
  • There are some conflicts you have to resolve. Then, do a git status, files already 'added' are successfully merged, while files marked as 'both modified' need to be fixed - open them, fix all conflicts (your version and the official version are marked with <<<<<< and >>>>>> signs). When you fix everything, add these files and then commit + push to finish the merge operation.

Note! If, while merging, you notice there are other things to fix, it's good practice to first complete the merge, commit, and then continue to fix (you can push at the end). Otherwise, your fixes will be "hidden" inside the commit representing the merge.

Merging from a pull request

If you want to be able to pull/merge from pull requests sent on the upstream repository, add the following line the [remote "upstream"] section of your .git/config file in the top folder of your repo:

fetch = +refs/pull/*/head:refs/remotes/upstream/pr/*

Once you do this, you can merge from a pull request using:

  • git fetch upstream followed by
  • git merge upstream/pr/8 (replace 8 with the pull request ID you want to merge from)
Clone this wiki locally