HOWTO-RELEASE

	Notes on Preparing a GDAL Source Release
	========================================


Prerequisites:

1) Check that the release is ready to go as far as ABI (binary compatibility)
   is concerned. This can be checked by comparing the installed headers of the
   candidate release with the installed headers of the previous release
   (diff -ur $(OLD_INSTALL_DIR)/include $(NEW_INSTALL_DIR)/include). The API
   is defined as all functions and classes exported by the CPL_DLL keyword.

  - For major and minor releases, there must be no function signature change
    for the C API. Only new functions are allowed.

  - For major releases, the allowed changes in C++ API should (or must?) be
    such that user calling C++ code can still compile against new headers
    without modification (existing methods can become virtual, default
    arguments can be added, new methods or members can be added)

  - For minor releases (1.6.1 versus 1.6.0), the C++ ABI stability must be
    preserved : no method signature change, no addition of virtual methods, no
    new members. Only non-virtual methods can be added.

    It may also be helpful to check:
      https://abi-laboratory.pro/tracker/timeline/gdal/

2) Delete existing fix_typos directory and run scripts/fix_typos.sh

Process :

1) "make completion" to regenerate scripts/gdal-bash-completion.sh
   if new command line switches have been added. scripts/completionFinder.py
   must also be edited before if new utilities/scripts are added/removed.

2) Update the release date, and number information in gcore/gdal_version.h.in
   (*NOT* gdal_version.h which is a generated file)
   Note: the format of GDAL_RELEASE_DATE should be YYYYMMDD.

   Update the release nickname of GDAL_RELEASE_NICKNAME to whatever makes sense
   to the release manager.

3) Update two instances of year in CITATION file to the current year.

4) Update "version" and "date-released" in CITATION.cff (Note: the DOI does
   *not* need to be updated as it is a generic one)

5) Update the VERSION file (if not already done)

6) Update the version information in the following files:
    - ./swig/python/gdal-utils/osgeo_utils/__init__.py (gdal-utils python package)
    - ./swig/python/README.rst (libgdal)

7) Update the GDAL_SOVERSION number at top of gdal.cmake according to the
   directions given in the comment preceding it.

8) Prepare release overview in the NEWS.md file. For example, to get all changes
   from v3.4.0 to current HEAD
     git log --reverse -v v3.4.0..HEAD . ":(exclude)autotest" ":(exclude)doc" ":(exclude).github"

   For a feature release, e.g 3.6.0, you can use scripts/generate_log_feature_release.py to generate a log without commit that went in the previous 3.5.x bugfix releases with:
     python3 scripts/generate_log_feature_release.py

  - commit new version to NEWS.md file.

  - for bugfixes releases, forward port additions of NEWS.md to master

9) Update PROJ_VERSION in .github/workflows/release.yml for the PROJ version to
   use with the Docker image we release

10) If this is a feature release (e.g 3.1), prepare a branch.

   git checkout master
   git pull origin master
   git checkout -b release/3.1
   git push origin release/3.1

11) Tag the release with a RC suffix:

   git checkout release/3.1
   git pull origin release/3.1
   git tag -a -m "Create tag v3.1.0RC1" v3.1.0RC1
   git push origin v3.1.0RC1

12) Once the release.yml GitHub jobs has published the source tarballs,
    get them from https://github.com/OSGeo/gdal/releases and upload them
    on download.osgeo.org,
    in /osgeo/download/gdal/X.Y.Z (where X.Y.Z is the version number)

    with ~/.ssh/config containing:

   Host osgeo7-*
        ProxyCommand ssh rouault@download.osgeo.org -W $(sed -e "s/^osgeo7-//;s/$/.lxd/" <<< "%h"):%p

13) Announce the release candidate availability to gdal-dev@
    Example: https://lists.osgeo.org/pipermail/gdal-dev/2019-June/050509.html

14) If new RC is needed, update gcore/gdal_version.h.in with the new date
    and update NEWS,and go to 7)

    If no new RC is needed, after a few days, raise a motion to gdal-dev@ for approval

15) Once the vote has positively completed,

15.0) For a new feature release, update the STABLE_BRANCH repository variable

    Go to https://github.com/OSGeo/GDAL/settings/variables/actions/STABLE_BRANCH
    and update the value to be release/x.y

15.1) Tag the release as final:

    git checkout v3.1.0RC1
    git tag -a -m "Create tag v3.1.0" v3.1.0
    git push origin v3.1.0

15.2) Upload source tarballs generated by github action on download.osgeo.org
      in /osgeo/download/gdal/X.Y.Z

15.3) In /osgeo/download/gdal, add a symlink from X.Y.Z to CURRENT (except for stable releases in a "old" branch).

  % ln -sf X.Y.Z CURRENT

16) Update GitHub to close the release milestone.
    Then create a new milestone for the next release.

17) Generate signed maven artifacts with GPG for Java bindings.
    This step is required in order to deploy the
    maven artifacts to the central Maven repository. Before this step can
    proceed you must set up a signing key as described here:

      http://central.sonatype.org/pages/working-with-pgp-signatures.html

 a) Each developer can use their own signing key although it is usually best to
    avoid constantly using a different key for releases as users will need to
    import the public key in order to verify the artifacts.

    Here are a quick set of steps to generate a signing key key.

       gpg --gen-key
       gpg --list-keys (and note the key id)
       gpg --keyserver hkp://pool.sks-keyservers.net --send-keys <key id>

    See the above link for more details.

  b) Run CMake with the following variables:

       1. GPG_KEY: the identifier for the signing keys
       2. GPG_PASS: the passphrase for the signing key (optional)

  c) Build the bindings: make java_binding

    Upon success you should see a file named "swig/java/build/bundle.zip"
    that contains all the maven artifacts with signatures. This file is what
    will be uploaded to maven central. See the next step.

19) Deploy maven artifacts to Maven central.

    NOTE: Before you can deploy to maven central you must set up an account
    in Sonatype JIRA. That can be done here:

        https://issues.sonatype.org/secure/Signup!default.jspa

    Once you have an account set up you must be associated with the gdal
    project. Create a ticket here asking to be associated with the project:

        https://issues.sonatype.org/browse/OSSRH

    The entire deployment process is described in detail here:

       http://central.sonatype.org/pages/manual-staging-bundle-creation-and-deployment.html
       http://central.sonatype.org/pages/releasing-the-deployment.html

    The following steps summarize the process.

a) Log into the Sonatype repository manager at https://central.sonatype.com. Use the
   same credentials as your Sonatype JIRA account.

b) Once log in, select "Publish" on the top

c) As description, type "GDAL <version>" and then choose the "bundle.zip"
   created in the previous Step 22.

18) Finalize the release on GitHub in https://github.com/OSGeo/gdal/releases
    and remove its draft status.

19) Update docker/README.md with the latest release

20) Announce release to :
    - major release: gdal-dev@lists.osgeo.org, gdal-announce@lists.osgeo.org, news_item@osgeo.org.
    - bugfix release: gdal-dev@lists.osgeo.org, gdal-announce@lists.osgeo.org

   Example:
    - bugfix release: https://lists.osgeo.org/pipermail/gdal-dev/2019-July/050543.html
    - feature release: https://lists.osgeo.org/pipermail/gdal-dev/2020-May/052117.html

Note: gdal-announce@ is moderated. Make sure that your email address is approved
('mod' tick disabled in https://lists.osgeo.org/mailman/admin/gdal-announce/members),
or your message manually approved, with an administrator of the list.

21) For a feature release: after it has been done, in the master branch, update
    the VERSION to the next one and in gcore/gdal_version.h.in, update
    GDAL_VERSION_MAJOR/_MINOR, GDAL_RELEASE_NAME (with a dev suffix, like "3.7.0dev"),
    and set GDAL_RELEASE_DATE to a date like {YEAR}9999.
    Update swig/python/gdal-utils/osgeo_utils/__init__.py to something like (3, 6, 99, 0)
    if master is 3.7.0dev

22) Update doc/source/about.rst, doc/source/download.rst and doc/source/download_past.rst
    to advertise the new release and link to the release notes.

23) For a feature release, enable a new version in the ReadTheDocs administration panel.
    a) Go to https://readthedocs.org/projects/gdal/versions/
    b) In the "Activate a version" tab, enter "release/X.Y" in the text entry and click on the Filter button
    c) Click on the Activate button
    d) Go to https://readthedocs.org/projects/gdal/, and in the "Compile a version" drop-down list,
       select the newt "release-X.Y" label and click on the "Compile a version" button
    e) Go to https://github.com/OSGeo/gdal/settings/variables/actions/STABLE_BRANCH and update it
    f) In the release/X.Y GDAL github branch, update the branch name of "source_file_url_template" in doc/source/conf.py