release-tasks

This file is internal information only. It lists the steps to be done when a
new release shall be issued.

***
***
*** Release preparation:
***
***


-3/ Send out notice to the mailinglist if anyone has outstanding
    issues or patches. This should happen at least a week before the
    release process starts. Ask for volunteer testers on Mac.

Subject: Release preparations

All,

we would like to start the release process for deal.II 8.3.0 soon. Please let us
know if you have any last minute things that need to be addressed (bugs,
documentation issues, configuration problems, etc.).

If you are running the current development version, please update your local
working copy and test if everything compiles, especially if you are running a
less common configuration (mac, old compilers, etc.).

Thanks!


-2/ Check all issues and pull-request on github. Create a list to see if
    there are things that we intended to fix before the release.


-1/ Update the list of publications. Standard text for the email:

Subject: Publications based on deal.II

All,

as you may know, we try to list all publications based on deal.II at
         http://dealii.org/publications.html
We use this list to justify the effort we spend on writing this software, both
to our universities as well as the funding agencies that support its
development.

In anticipation of the next release, we would like to update this page. If you
have (or know of) a publication that uses deal.II for numerical results and
that isn't already listed, please let us know so we can put it on there. For
this purpose, publications also include MSc, Diploma or PhD theses, or
anything else that may seem appropriate.

Thanks!

  Send this as BCC to
    dealii@googlegroups.com
    dealii-developers@googlegroups.com
    num.info@ganymed.iwr.uni-heidelberg.de
    aspect-devel@geodynamics.org


-1a/ Start release paper process with email to all current (principal)
 developers:

Subject: 9.0 Release Paper

All,
Timo and I have started to work on a few things necessary for the next
release. In particular, we would like to get the release paper started.

To this end:
* Please check out https://github.com/dealii/release-papers
* If you think that you have contributed in a way that warrants co-authorship,
  please add yourself to the list of authors for the 9.0 paper
* If you think that someone other than just us maintainers should be a
  co-author, please nominate that person here
We think that these last two points are important -- we want the list of
co-authors to reflect who actually contributed, rather than inherited
rights in the project, because that makes it clear to current and future
participants in the project that they can hope for formal recognition of
their work in terms of things they can put on their CV.

As far as content of the paper is concerned: I put together a list of
possible topics -- please take a look. 

As far as the material I tentatively put into the paper: if you're willing
to write a section, can you attach your name to it somehow in the next
couple of days?

Best
  Wolfgang & Timo


-1b/ update the authors list on the homepage authors.html by
     cross-referencing doc/news/changes.h

     Get the list using
        egrep '[0-9]+/[0-9]+/[0-9]+' doc/news/changes/*/* | \
           perl -p -e 's/^.*\(//g; s#, *[0-9/]+\)##g; s/, */\n/g;' | \
           sort |uniq

     Compare with the commit list:
       git log --date=short --format="%an %aE" v8.3.0..HEAD | sort | uniq



-1c/ The list of contributors to the current release should also be copied to
     the end of the release paper:

Developers:
  Daniel Arndt
  Wolfgang Bangerth
  Denis Davydov
  Timo Heister
  Luca Heltai
  Guido Kanschat
  Martin Kronbichler
  Matthias Maier
  Jean-Paul Pelteret
  Bruno Turcksin
  David Wells

Contributors for 9.0: (updated 2018-04-19)
  Giovanni Alzetta
  Julian Andrej
  Daniel Arndt
  Rajat Arora
  Wolfgang Bangerth
  Vishal Boddu
  Benjamin Brands
  Lucas Campos
  Praveen Chandrashekar
  Jie Cheng
  Emma Cinatl
  Conrad Clevenger
  Ester Comellas
  Sambit Das
  Denis Davydov
  Giovanni Di Ilio
  Nivesh Dommaraju
  Marc Fehling
  Niklas Fehn
  Menno Fraters
  Anian Fuchs
  Daniel Garcia-Sanchez
  Rene Gassmoeller
  Nicola Giuliani
  Anne Glerum
  Christoph Goering
  Alexander Grayver
  Timo Heister
  Luca Heltai
  Samuel Imfeld
  Daniel Jodlbauer
  Guido Kanschat
  Vishal Kenchan
  Andreas Kergassner
  Eldar Khattatov
  Ingo Kligge
  Uwe Köcher
  Joachim Kopp
  Katharina Kormann
  Martin Kronbichler
  Ross Kynch
  Konstantin Ladutenko
  Tulio Ligneul
  Karl Ljungkvist
  Matthias Maier
  Santiago Ospina
  Alexey Ozeritsky
  Jean-Paul Pelteret
  Dirk Peschka
  Simon Puchert
  E. G. Puckett
  Lei Qiao
  Ce Qin
  Jonathan Robey
  Alberto Sartori
  Daniel Shapero
  Ben Shields
  Simon Sticko
  Oliver Sutton
  Bruno Turcksin
  Zhuoran Wang
  Xiaoyu Wei
  David Wells
  Michał Wichrowski
  Julius Witte
  Feimi Yu
  Weixiong Zheng


0/ Do some basic testing as always

0a/ Rerun cppcheck across the source files:
    cppcheck --force -j4 --enable=all -I./include/ ./source/*/*.cc >cppcheck-results.txt 2>&1

    and look for anything that should obviously be fixed.


0b/ Check for doxygen formatting problems by running contrib/utilities/checkdoxygen.py:
      find include -name "*h" -print | xargs -n 1 ./contrib/utilities/checkdoxygen.py
    and push the corresponding changes


0c/ Fix formatting bugs reported by: 

    cd include;
    find . -name "*h" -print | while read file;do ../contrib/utilities/wrapcomments.py $file >temp;done

    then rewrap comments in include/

    cd include; 
    find . -name "*h" -print | while read file;do ../contrib/utilities/wrapcomments.py $file >temp;mv temp $file;done

    make sure you don't mess up polynomials_bdm.h ...


    Also check:
    grep -l '@ref[^"]*"[^"]*$' **/*.h
    grep -l '@ref$' **/*.h

    Push the corresponding changes.


0d/ Check that doxygen produces no errors when generating offline docs.
    Especially check that the tutorial dot graph gets generated


0e/ Run the copyright script:
      ./contrib/utilities/update-copyright
      git checkout -b update-copyright
      git commit -a -m "Update copyright years."
      git push origin update-copyright
      hub pull-request -m "Update copyright years."
    and push the corresponding changes


0f/ update Trilinos and PETSc to the latest release on the tester and update the blurb at:
    doc/external-libs/trilinos.html
    doc/external-libs/petsc.html

0g/ Run codespell: e.g., inside emacs' compilation-mode run

        codespell --disable-colors ./contrib/ ./cmake/ ./doc/ ./examples/ ./include/ ./source/

    or the same (without --disable-colors) in the terminal.


*** Caveat: for a minor version x.y.Z,
*** 1-3 must be performed on the corresponding release branch, e.g. 'dealii-8.2'
*** AND on HEAD


1/  Create new changes file:
    - Adjust the header of doc/news/header so that it reflects
      the versions in question
    - Also adjust the copyright dates
    - Run the following commands from above the source dir:
        mkdir build-doc
        cd build-doc
        cmake ../dealii -DDEAL_II_COMPONENT_DOCUMENTATION=ON
        make documentation
        cp doc/news/changes.h ../dealii/doc/news/8.4.2-vs-8.5.0.h
        cd ../dealii
        git checkout -b update-changes-file
        git add  doc/news/8.4.2-vs-8.5.0.h
        git commit -m "Update the changelog file for the release." doc/news/8.4.2-vs-8.5.0.h
        git rm doc/news/changes/{major,minor,incompatibilities}/*
        git commit -m "Remove now obsolete files." doc/news/changes/{major,minor,incompatibilities}
        git push origin update-changes-file
        hub pull-request -m "Replace individual files by one changelog for the whole release."
    - Adjust the header of doc/news/header back so that it can
      serve as the running header for the next release cycle.

1a/ Adjust doc/users/doxygen.html to link to the to-be-created TAG file.
    then do a pull request

4/  If a x.y.0 release, it is now time to create a release branch:

  git branch dealii-8.2       # exactly 'dealii-X.Y' to remain consistent!

  # Update VERSION from 8.2.0-pre to 8.2.0-rc1
  #
  # Note: Please do not use "8.2.0" directly because the soname is derived
  # from the current version number. Therefore, 8.2.0 must only be used for
  # the final, tagged and distributed code.

  git commit -a -m "update VERSION"

  git push origin dealii-8.2  # where origin is the remote pointing to
                              # github.com/dealii/dealii.git

  Note: Without a pull request!


5/ Update the VERSION from 8.2.0-pre to 8.3.0-pre on master

  git commit -a -m "update VERSION"

  git push origin master  # where origin is the remote pointing to
                          # github.com/dealii/dealii.git

  Note: Without a pull request!


6/ update the official tester to test on the release branch dealii-8.2

   An empty checkout in a folder 'dealii-8.2' can be obtained via

   git clone --branch dealii-8.2 git://github.com/dealii/dealii.git deal-8.2

6a/ On mainline, do something like this to require the current dev version
    for the tutorials and in the documentation:

    perl -pi -e 's/8.4 QUIET/8.5.0 QUIET/g;' examples/*/CMakeLists.txt
 
    also check doc/users/* and tests/*:

    grep "FIND_PACKAGE(deal.II" -r doc/ tests/
   
    git commit -a -m "Require the current version of deal.II."
    [ pull request ]


7/ Create an AUTHORS file in the top-level directory of the branch that
   contains a text-only copy of the authors.html file from the website.
   You can start from 
   lynx -dump -nolist https://www.dealii.org/authors.html >AUTHORS
   and format it like this:
   https://github.com/dealii/dealii/blob/dealii-8.3/AUTHORS

   Update LICENSE to point to the AUTHORS file:

   "[...] refers to the people listed in the file AUTHORS."

   git add AUTHORS
   git commit -a -m "update AUTHORS"

   git push origin dealii-8.2

   Note: Without a pull request!


7a/ Send prerelease announcement to dealii-developers@googlegroups.com

Subject: Release testing, part1 (step 7a)

Dear developers,

we are in the process of releasing a new version of deal.II.

It would be great if you could test it on your machine with your typical
configuration. For this update your git repository and switch to the
release branch:
  git remote update
  git checkout dealii-8.3

If no further regressions show up we will release [planned date]

Thanks,
Wolfgang Bangerth, Timo Heister, Guido Kanschat, and Matthias Maier



8/ Remove unfinished tutorial programs.
   For 8.5, these are steps 47, 50

   a) Delete directories on the branch:

     cd examples
     git rm -r step-47 step-50 
     git commit -a -m "removed unfinished steps (release tasks step 8)."

   b) These steps should also not be listed on the branch in
      doc/doxygen/tutorial/tutorial.h.in

     [ pull request ]


   c) Make sure all images are moved to the homepage repository. See:
      https://svnhp.dealii.org/trunk/homepage/images/steps/readme.txt


9/  Write up a short release note and save it as announce-8.3
9a/ Write the release paper in the release-papers/ subdirectory

10/ Test the branch thoroughly:

    a) Run a full testsuite run locally,

    b) Have a look at the test results on cdash

    c) Configure, build and run all examples by hand (the testsuite only
       runs a subset of it):

      cd [install]/examples
      for i in step-* ; do \
        (cd $i ; cmake -DDEAL_II_DIR=../.. . ; make ; make run) ; done

      This step will require looking at the output and checking whether
      anything untoward is happening.

10a/ Do the same for the code gallery examples: They should at the
     very least compile. If possible, also run them to make sure they
     don't trip up any exceptions.

11/ In a clean source directory of the dealii-8.2 branch, do
      mkdir builddoc
      cd builddoc
      cmake -DDEAL_II_COMPONENT_DOCUMENTATION=ON -DCMAKE_INSTALL_PREFIX=$PWD/../installeddoc ../
      make -j 10 documentation
      cd ../installeddoc/doc
      for i in `find . | egrep '\.html$'` ; do \
          perl ../../doc/doxygen/scripts/validate-xrefs.pl $i ; done

     If some of the deleted tutorial programs were linked to somewhere
     else, resolve the unresolved links by adding corresponding files
     to the doc/doxygen/headers directory. The content of such files
     looks like shown here:
        svn cat http://www.dealii.org/svn/dealii/branches/releases/Branch-7-0/deal.II/doc/doxygen/headers/step-32.h


[ some time with bugfixing and commits on the release branch ]


***
***
*** Publish a release, or release candidate.
***
***


12/ Push the button:

    a) Change VERSION to 8.2.0 for a release and to 8.2.0-rc1 for a release
       candiate and commit:
       git commit -m "update VERSION for release"

    b) (Signed) tag the commit with:

      # for the final release:
      git tag -s -m "deal.II Version 8.3.0" v8.3.0
      # or alternatively for a release candidate:
      git tag -s -m "deal.II Pre-Release Version 8.3.0-rc1" v8.3.0-rc1

      You need a working gnupg key for this. (You should have anyway :-P)

    c) Push changes to github:

      # where origin is the remote pointing to github.com/dealii/dealii.git
      git push origin dealii-8.3
      git push origin v8.3.0


13/ Create the tar files:

    a) github automatically generates a source tarball from the current
    repository state, see https://github.com/dealii/dealii/releases

    b) Download the source tarball from github, verify that its contents is
    what we expect, e.g.

      # in a clean git repository:
      git checkout v8.2.0 # or git checkout v8.2.0-rc1
      rm -r *
      tar --strip-components=1 -xvf dealii-8.2.0.tar.gz (or dealii-8.2.rc1.tar.gz)
      git status

    Now, the last git status must not show any modified contents!
      TH: this is not true, because of .gitattributes, so ignore changes in ./tests/

    Cryptographically sign it (detached, armored signature):

      gpg --detach-sign --armor dealii-8.2.0.tar.gz

      (Guido, Timo and Matthias have a suitable gpg in the "pgp strong set")

    c) Create full offline_doc tarball

    In a clean working copy of the tagged release version run the script

      ./make_offline_doc.sh 8 2 0
      # or alternatively for a release candidate
      ./make_offline_doc.sh 8 2 0-rc1

    to create dealii-8.2.0-offline_documentation.tar.gz
    (dealii-8.2.0-rc1-offline_documentation.tar.gz). This step needs to be
    done on a machine that has both a reasonably new doxygen version as
    well as a dot version that can produce pngs. wolfgang's bloc507d has
    both of these programs installed in /home/bangerth/bin/x86/bin.

    d) Also sign it:

      gpg --detach-sign --armor dealii-8.2.0-offline_documentation.tar.gz


14a/ Create a pre-release on github:

  https://github.com/dealii/dealii/releases/new

    Tag: dealii-8.2.0-rc1 @master
    Release title: deal.II pre-release version 8.2.0-rc1

    Description: ""

    Attach dealii-8.2.0-rc1.tar.gz (yes, once again)
    Attach dealii-8.2.0-rc1.tar.gz.asc
    Attach dealii-8.2.0-rc1-offline_documentation.tar.gz
    Attach dealii-8.2.0-rc1-offline_documentation.tar.gz.asc

14b/ Create a release on github:

  https://github.com/dealii/dealii/releases/new

    Tag: dealii-8.2.0 @master
    Release title: deal.II version 8.2.0

    Description:
    [Short version of release notes as found in announce-8.2]
    A full list of changes can be found at
    http://www.dealii.org/developer/doxygen/deal.II/changes_between_8_2_1_and_8_3.html

    Attach dealii-8.2.0.tar.gz (yes, once again)
    Attach dealii-8.2.0.tar.gz.asc
    Attach dealii-8.2.0-offline_documentation.tar.gz
    Attach dealii-8.2.0-offline_documentation.tar.gz.asc


***
*** Caveat: Every further commit on an actual release at this point forces
*** an increase in the patch number, i.e. 8.2.0 -> 8.2.1.
***
*** Go back to 12/ until a release is tagged
***


15/ Generate the documentation on the webserver.
    Guido: Man nehme scripts/make_documentation.sh aus unserem privaten SVN-Repository und ersetze in der cmake-Zeile "Git ..." durch "X.Y.Z"

16/ Adjust header.include on homepage:
      change links to the documentation of the most recent version
      change the link to the changes_after_X_Y_Z.html file
      (possibly other items -- please update this list)


17/ Ask Luca for Mac packages. Those can be added as additional download
    options to the freshly created release. Mention new naming convention
    "dealii-8.2.0-.*" for attachments


18/ Finish writing the announcement


18b/ Adjust news.html in the deal.II homepage repo: new entry for the
     release using the link to the copied changes.h file from above; commit.
     Rotate the news entry also in the short news blurb on the front page in
     index.html

19/ announce the release by sending an email to announce-list (file in this
    directory) with subject:
      Finite Element Software deal.II Version 8.4.0 released


19a/ Send a note to the Facebook and Google+ accounts


19b/ Update the deal.II wikipedia page: http://en.wikipedia.org/wiki/Deal.II


19d/ Send thank-you email and list the people already referenced in step -1b above
     Sample text:

I would like to follow up on the announcement of this release by publicly
saying again how much we appreciate the many contributions from those who
have sent it code, bug reports, fixed grammar and typos, or have helped in
any other way. Many thanks!

The ChangeLog lists at least the following people to whom thanks are due
(though I am certain that I am forgetting someone):


20/ Celebrate!