agda/notes/agda-releases.txt

Tested with `ghc-8.10.5` and `cabal-install 3.4.0.0`.

When releasing the following procedure can be followed:

* Verify that the Travis builds and GitHub workflows have no errors.

* First, release a release candidate (see
  notes/agda-stable-releases-candidates).

* Use the branch used for releasing the release candidate.

* Finish the release notes in the CHANGELOG.

* Replace in the CHANGELOG

  https://agda.readthedocs.io/en/latest

  by

  https://agda.readthedocs.io/en/vMAJORVERSION

* Run the `closed-issues-for-milestone` program for adding the list of
  closed issues to the CHANGELOG.

* Because some titles of some issues can generate new white-space
  issues after running the `closed-issues-for-milestone` program, run

    make check-whitespace

  and fix the issues both in the CHANGELOG file and GitHub.

* Update the README.md, if necessary.

* Update the list of contributors if necessary.

  Note: This is duplicated in the following locations:

  - Agda.cabal
  - doc/user-manual/conf.py
  - doc/user-manual/team.rst
  - LICENSE

* Update the LICENSE file, if necessary.

* Update Stackage resolvers, if necessary.

* Update the copyright year range in

  - Agda.cabal
  - /doc/user-manual/conf.py
  - LICENSE

* Check the date and version in `/src/data/latex/agda.sty`.

* Update in the bug tracker the milestone field of open issues to the
  next Agda version.

* Get a clean Agda repository.

    MAJORVERSION=<current-development-version-eg-2.4.2>
    VERSION=<current-released-version-eg-2.4.0.2>
    git clone git@github.com:agda/agda.git agda-release
    cd agda-release
    git checkout master

* Update the Agda version

    ./src/release-tools/change-version.bash VERSION MAJORVERSION

* Obtain and install the standard library branch related to the Agda:

    make up-to-date-std-lib

* Obtain and install the cubical library branch related to the Agda:

    make up-to-date-cubical

* Run the test-suite:

    make compile-emacs-mode
    make test

  Note that "compile-emacs-mode" invokes "agda-mode compile", which should
  ensure that the Emacs mode can be compiled without errors or
  warnings (except for the "cl package required at runtime" warning).

1) Remove the Cabal test-suite from Agda.cabal.

2) Remove -Werror and -fprof-auto from Agda.cabal (this is required by
  `cabal --check`).

3) Removed unnecessary dependencies from stack-XYZ.yaml files:

  + Removed QuickCheck dependency
  + Removed tasty-* dependencies
  + Removed local package (src/size-solver)

4) Added to the extra-source-files field in Agda.cabal the file (see
  Issues #4216):

    doc/user-manual.pdf

* Update the user manual:

    make user-manual-pdf

* Build source distributions:

    cabal configure
    cabal check
    cabal sdist

* Build documentation for uploading to Hackage.

    cabal haddock --haddock-for-hackage

* Ensure that the package builds properly (with multiple versions of
  GHC if possible) in Linux, macOS and Windows.

    BASE=`pwd`
    cd ${TMPDIR:-/tmp}
    tar xzf $BASE/dist-newstyle/sdist/Agda-$MAJORVERSION.tar.gz
    cd Agda-$MAJORVERSION
    cabal install --program-suffix=-$MAJORVERSION
    agda-$MAJOR_VERSION --version
    agda-mode-$MAJOR_VERSION compile

* Tag the relase (do not forget to record the changes above first):

    cd $BASE
    git tag -a v$MAJORVERSION -m "Agda $MAJORVERSION stable release"

* Upload the tarball and the documentation to Hackage:

    cd $BASE
    cabal upload --publish dist-newstyle/sdist/Agda-$RC_VERSION.tar.gz
    cabal upload --publish -d dist-newstyle/Agda-$RC_VERSION-docs.tar.gz

* Revert changes made in 1), 2), 3) and 4).

* Push all changes (in the release-$MAJORVERSION branch):

    git push --follow-tags

* New CHANGELOG (see Issue #4705):

  ** In a commit:

     *** Move the CHANGELOG for $MAJORVERSION to a new entry in
         doc/release-notes/<version-written-with-dashes>.md.

     *** Add doc/release-notes/<version-written-with-dashes>.md. to
         the extra-source-files field in Agda.cabal.

  ** In a different commit: Create a new CHANGELOG file.

* Close in the bug tracker the milestone $MAJORVERSION.

* Update Agda Manual on Readthedocs.org (see Issues #2844 and #3035)

  ** You need Admin permissions on the Agda readthedocs.org project
     (current admins: asr, andreasabel, phile314)

  ** Go to readthedocs.org -> Agda Project -> Versions

     and mark $MAJORVERSION as active

  ** Go to readthedocs.org -> Agda Project -> Admin -> Advanced Settings

     and set the default documentation version to $MAJORVERSION

  ** If a release candidate was released then remove the associated
     documentation.

* Update the Agda Wiki:

  ** Update the Download page:

     *** Move the current version information to the old releases
         section.

     *** Update the last release information.

  ** Update the Main page.

  ** Is the current version of the standard library compatible with
     the new version of Agda? If so, to update the standard library
     page.

* If we are releasing a bux-fix release then deprecate in Hackage the
  buggy version.

* Announce the release of the new version on the Agda mailing lists
  (users and developers).

* Enable the released version of Agda on Stackage, if necessary.