1Maintainers Guide 2================= 3 4This page contains instructions for project maintainers about making releases, creating source packages, managing CI, etc. 5 6If you want to make a contribution to the project, see the :doc:`Contributing Guide </devdocs/contributing>` instead. 7 8Creating source packages 9------------------------ 10 11Edit ``cmake/ConfigDefault.cmake`` and set ``GMT_PACKAGE_VERSION_MAJOR``, ``GMT_PACKAGE_VERSION_MINOR``, and 12``GMT_PACKAGE_VERSION_PATCH``. Also set ``GMT_PUBLIC_RELEASE`` to ``TRUE``. Then create source packages with:: 13 14 cmake --build . --target gmt_release # export the source tree and documentation 15 cmake --build . --target gmt_release_tar # create tarballs (in tar.gz and tar.xz formats) 16 17Packaging 18--------- 19 20Currently, packaging with CPack works on macOS (Bundle, TGZ, TBZ2), Windows (ZIP, NSIS), and UNIX (TGZ, TBZ2). On 21Windows you need to install `NSIS <http://nsis.sourceforge.net/>`_. After building GMT and the documentation, 22build and place the executables, including the supplements, with:: 23 24 cmake --build . --target install 25 26 27and then create the package with either one of these:: 28 29 cmake --build . --target package 30 cpack -G TGZ|TBZ2|Bundle|ZIP|NSIS 31 32Continuous Integration 33---------------------- 34 35We use GitHub Actions Continuous Integration (CI) services to build and test the project on Linux, macOS, and Windows. 36 37There are 11 configuration files located in ``.github/workflows/``: 38 391. ``backport.yml`` (Backports Pull Requests with specific labels into the matching branch) 40 41 This workflow backports Pull Requests labelled by "backport xxx" into the "xxx" branch. For example, the workflow 42 backports Pull Requests labelled "backport 6.1" into the "6.1" branch. This workflow does not apply to Pull Requests 43 from forks (`issue #3827 <https://github.com/GenericMappingTools/gmt/issues/3827>`_). 44 452. ``build.yml`` (Build GMT and run a few simple tests) 46 47 This workflow is run on every commit to the *master* branch and Pull Request branches. The workflow configures 48 and builds GMT on Linux, macOS, and Windows and runs some simple tests. The workflow uses the scripts in the ``ci/`` 49 directory for downloading/installing dependencies (``ci/download-coastlines.sh`` and ``ci/install-dependencies-*.sh``), 50 configuring GMT (``ci/config-gmt-*.sh``), building GMT, and running some simple tests (``ci/simple-gmt-tests.*``). 51 523. ``check-links.yml`` (Check links in the repository and website) 53 54 This workflow is run every Sunday at 12:00 (UTC) to check all external links in plaintext and HTML files. It will 55 create an issue if broken links are found. 56 574. ``ci-caches.yml`` (Cache GMT remote data files and Windows vcpkg libraries needed for GitHub Actions CI) 58 59 This workflow is run every Sunday at 12:00 (UTC). If new remote files are needed urgently, maintainers can 60 manually uncomment the 'pull_request:' line in the ``ci-caches.yml`` file to refresh the cache. The workflow uses the 61 script ``ci/install-dependencies-windows.sh`` to cache the vcpkg libraries. 62 635. ``code-validator.yml`` (Validate code consistency) 64 65 This workflow is run on every commit to the *master* branch and Pull Request branches. It runs the scripts 66 ``src/gmt_make_PSL_strings.sh``, ``src/gmt_make_enum_dicts.sh``, and ``src/gmt_make_module_purpose.sh`` and exits 67 with an error if any changes are detected by git. It also checks the GMT version year in ``ConfigDefault.cmake`` and 68 the permissions of the bash scripts. 69 706. ``docker.yml`` (Build GMT on different Linux distros using dockers) 71 72 This workflow is run when Pull Requests are merged into the *master* branch. It downloads/installs dependencies 73 and configures and builds GMT on different Linux distributions using dockers. 74 757. ``docs.yml`` (Build documentation on Linux/macOS/Windows) 76 77 This workflow is run when Pull Requests are merged into the *master* branch, if the Pull Request involved changes to 78 files in the ``doc/``, ``.github/workflows/``, or ``ci/`` directories. 79 80 The workflow also handles the documentation deployment: 81 82 * Updating the development documentation by pushing the built HTML pages from the *master* branch into the ``dev`` 83 folder of the *gh-pages* branch. 84 * Updating the ``latest`` documentation link to the new release. 85 868. ``draft-release.yml`` (Drafts the next release notes) 87 88 This workflow is run to draft the next release notes when new tags are made. It downloads GMT tarballs, macOS bundle 89 and Windows installers from the GMT FTP server, calculate their sha256sums and save into `gmt-X.Y.Z-checksums.txt`, 90 draft the release notes, and uploads them as release assets. Maintainers still need to review the draft release 91 notes and click the "publish" button. 92 939. ``lint-checker.yml`` (Run cppchecks) 94 95 This workflow is run every day at 12:00 (UTC) to run `admin/run_cppcheck.sh` on the source code. 96 9710. ``scm-check.yml`` (Check for new scientific color maps releases) 98 99 This workflows is run every Sunday at 12:00 (UTC) to check whether there has been a new release of the 100 `Scientific colour maps <http://www.fabiocrameri.ch/colourmaps.php>`_. If a new release is found, it will open an 101 issue automatically. 102 10311. ``tests.yml`` (Tests on Linux/macOS/Windows) 104 105 This workflow is run when Pull Requests are merged into the *master* branch, if the Pull Request involved changes 106 to the folders that contain source code, workflows, tests, or scripts for generating documentation figures. It runs 107 the full GMT test suite on Linux, macOS, and Windows. 108 10912. ``release-drafter.yml`` (Drafts the next release notes) 110 111 This workflow is run to update the next releases notes as pull requests are merged into master. 112 113Updating the changelog 114---------------------- 115 116The Release Drafter GitHub Action will automatically keep a draft changelog at 117https://github.com/GenericMappingTools/gmt/releases, adding a new entry every time a Pull Request (with a proper label) 118is merged into the master branch. This release drafter tool has two configuration files, one for the GitHub Action 119at ``.github/workflows/release-drafter.yml``, and one for the changelog template at ``.github/release-drafter.yml``. 120Configuration settings can be found at https://github.com/release-drafter/release-drafter. The maintenance documentation 121for this workflow is based on the `PyGMT Maintenance Documentation <https://www.pygmt.org/dev/maintenance.html>`_. 122 123The drafted release notes are not perfect, so we will need to tidy it prior to publishing the actual release notes at 124https://docs.generic-mapping-tools.org/latest/changes.html. 125 1261. Go to https://github.com/GenericMappingTools/gmt/releases and click on the 'Edit' button next to the current draft 127 release note. Copy the text of the automatically drafted release notes under the 'Write' tab to 128 ``doc/rst/source/changes.rst``. 1292. Open a new Pull Request using the title 'Changelog entry for GMT X.Y.Z' with the updated release notes, so that other 130 people can help to review and collaborate on the changelog curation process described next. 1313. Edit the change list to remove any trivial changes (updates to the README, typo fixes, CI configuration, etc). 1324. Edit the formatting to use :doc:`/devdocs/rst-cheatsheet`. 1335. Add links in the changelog to elements of the documentation as appropriate. 134