Contributors Guide

This is a community driven project and everyone is welcome to contribute. The project is hosted at the GMT GitHub repository.

The goal is to maintain a diverse community that’s pleasant for everyone. Please be considerate and respectful of others. Everyone must abide by our Code of Conduct and we encourage all to read it carefully.

Ways to Contribute

Ways to Contribute Documentation and/or Code

  • Tackle any issue that you wish! Please leave a comment on the issue indicating that you want to work on it. Some issues are labeled as “good first issues” to indicate that they are beginner friendly, meaning that they don’t require extensive knowledge of the project.

  • Make a tutorial or example of how to do something.

  • Improve the API documentation.

  • Contribute code you already have. It doesn’t need to be perfect! We will help you clean things up, test it, etc.

Ways to Contribute Feedback

  • Provide feedback about how we can improve the project or about your particular use case. Open an issue with feature requests of bug fixes, or post general comments/questions on the forum.

  • Help triage issues, or give a “thumbs up” on issues that others reported which are relevant to you.

Ways to Contribute to Community Building

  • Participate and answer questions on the GMT Community Forum.

  • Participate in discussions at the monthly GMT Community Meetings, which are announced on the forum governance page.

  • Cite GMT when using the project.

  • Spread the word about GMT or start the project!

Providing Feedback

Reporting a Bug

  • Find the Issues tab on the top of the GitHub repository and click New Issue.

  • Click on Get started next to Bug report.

  • Please try to fill out the template with as much detail as you can.

  • After submitting your bug report, try to answer any follow up questions about the bug as best as you can.

Submitting a Feature Request

  • Find the Issues tab on the top of the GitHub repository and click New Issue.

  • Click on Get started next to Feature request.

  • Please try to fill out the template with as much detail as you can.

  • After submitting your feature request, try to answer any follow up questions as best as you can.

Submitting General Comments/Questions

There are several pages on the Community Forum where you can submit general comments and/or questions:

  • For questions about using GMT, select New Topic from the Q&A Page.

  • For general comments, select New Topic from the Lounge Page.

  • To share your work, select New Topic from the Showcase Page.

General Guidelines

Resources for New Contributors

Please take a look at these resources to learn about Git and pull requests (don’t hesitate to ask for help):

Getting Help

Discussion often happens in the issues and pull requests. For general questions, you can post on the GMT Community Forum. We also host community meetings roughly monthly to discuss GMT development, which are announced on the GMT Community Forum.

Pull Request Workflow

We follow the git pull request workflow to make changes to our codebase. Every change made goes through a pull request, even our own, so that our continuous integration services have a change to check that the code is up to standards and passes all our tests. This way, the master branch is always stable.

General Guidelines for Making a Pull Request (PR):

  • Open an issue first describing what you want to do. If there is already an issue that matches your PR, leave a comment there instead to let us know what you plan to do.

  • Each pull request should consist of a small and logical collection of changes.

  • Larger changes should be broken down into smaller components and integrated separately.

  • Bug fixes should be submitted in separate PRs.

  • Describe what your PR changes and why this is a good thing. Be as specific as you can. The PR description is how we keep track of the changes made to the project over time.

  • Do not commit changes to files that are irrelevant to your feature or bugfix (eg: .gitignore, IDE project files, etc).

  • Write descriptive commit messages. Chris Beams has written a guide on how to write good commit messages.

  • Be willing to accept criticism and work on improving your code; we don’t want to break other users’ code, so care must be taken to not introduce bugs.

  • Be aware that the pull request review process is not immediate, and is generally proportional to the size of the pull request.

General Process for Pull Request Review:

After you’ve submitted a pull request, you should expect to hear at least a comment within a couple of days. We may suggest some changes or improvements or alternatives.

Some things that will increase the chance that your pull request is accepted quickly:

  • Write a good and detailed description of what the PR does.

  • Write tests for the code you wrote/modified.

  • Readable code is better than clever code (even with comments).

  • Write documentation for your code and leave comments explaining the reason behind non-obvious things.

  • Include an example of new features in the gallery or tutorials.

Pull requests will automatically have tests run by GitHub Actions. Github will show the status of these checks on the pull request. Try to get them all passing (green). If you have any trouble, leave a comment in the PR or get in touch.

Setting up your environment

For editing the documentation locally and contributing code, you will need a development environment. To set up a development environment, follow the steps for building GMT paying attention to several “Note for developers” that provide helpful or necessary information for running tests and building the documentation.

To enable testing, you need to uncomment the following lines in your ConfigUserAdvanced.cmake when configuring GMT:

enable_testing()
set (DO_EXAMPLES TRUE)
set (DO_TESTS TRUE)

set (SUPPORT_EXEC_IN_BINARY_DIR TRUE)

set (DO_API_TESTS ON)

Optionally, uncomment the following line to run tests on the supplement modules:

set (DO_SUPPLEMENT_TESTS ON)

Optionally, uncomment the following line and change 4 to the number of ctest jobs to run simultaneously:

set (N_TEST_JOBS 4)

Updating the development source codes

Assuming you did not delete the build directory, this is just as simple as:

cd <path-to-gmt>
git pull
cd build
cmake --build .
cmake --build . --target install

CMake will detect any changes to the source files and will automatically reconfigure. If you deleted all files inside the build directory you have to run CMake again manually.

Using build and test aliases

The file /admin/bashrc_for_gmt contains useful aliases for building and testing GMT that some developers chose to use. New pull requests with other aliases that you find helpful are welcome. This file is version controlled, so you should copy the file to a different location in order to edit and use it. For example, use these commands to copy it to your home directory:

cd <path-to-gmt>
cp admin/bashrc_for_gmt ~/.bashrc_for_gmt

Here are the steps for setting up bashrc_for_gmt after copying it to a new location:

  • If you do not have ninja installed, you will need to change builder=ninja to builder=make and Bname="Ninja" to Bname="Unix Makefiles". Ninja is recommended for speeding up build times.

  • You may need to update pngview=open and pdfview=open depending on your preferred program for viewing files.

  • Optionally, change ncores=4 to the number of cores to use for building and running tests.

  • Change MATLAB=/Applications/MATLAB_R2019a.app to the path for your version of the MATLAB app.

  • Set REPO_DIR to the path that contains the local git clone copy of the GMT repository.

  • Set DATA_DIR to the path that contains the folders dcw-gmt-2.0.0/ and gshhg-gmt-2.3.7/ for the dcw and gshhg datasets respectively. If these folders are not located in the same path, you can instead delete the line (DATA_DIR=<path to directory containing GSHHG and DCW>) and set the individual paths to the GSHHG and DCW source by changing (export GMT_GSHHG_SOURCE=${DATA_DIR}/gshhg-gmt-2.3.7) and (export GMT_DCW_SOURCE=${DATA_DIR}/dcw-gmt-2.0.0).

  • Edit the file ~/.bashrc to include the line source <path>/bashrc_for_gmt. If you set up bashrc_for_gmt as a hidden file in your home directory, this line should be source ~/.bashrc_for_gmt.

Here are some of the shortcuts included in bashrc_for_gmt:

  • gmt6 and gtop can be used to quickly cd to the top of the GMT source directory and repository base respectively.

  • gmtfind can be used to list all source, docs, scripts, and text files where a string appears in the file (e.g., gmtfind "Grid increment is" returns all files that contain the string ‘Grid increment is’). This includes all files recursively from the current working directory; gtop or gmt6 can be used prior to this command to get to the source directory or repository base.

  • cmakegmtd, cmakegmtr, and cmakegmtx configures cmake for debug, release, and XCode debug respectively.

  • dlog and rlog can be used to open the debug and release build check error logs respectively.

  • There are several aliases with various combinations of pulling new changes, deleting the build directories, configuring cmake, and building the source code. Each of these are documented with comments in bashrc_for_gmt.

  • checkdbuild and checkrbuild can be used to run the tests for the debug and release builds respectively.

  • vpngdbuild and vpdfdbuild can be used to open the results from all failing image-based tests.

  • view_png_failures_r and view_pdf_failures_r can be used for view failures of the release build with a lag between opening each file.

Contributing Documentation

If you’re browsing the documentation and notice a typo or something that could be improved, please consider letting us know. You can either create an issue on GitHub, or click the “Edit on GitHub” button at the top right corner of the documentation, and submit a pull request.

The GMT documentation is written in the plaintext markup language reStructuredText (reST) and built by documentation generator Sphinx. The reST plaintext files for the GMT documentation are located in the doc/rst/source folder. You may need to know some basic reST syntax before making changes. Please refer to our reStructuredText Cheatsheet for details.

Building the documentation

Usually you don’t need to build the documentation locally for small changes. To build the GMT documentation you need to build GMT from source. Be sure to also satisfy the development dependencies before proceeding. Have a look at the options in cmake/ConfigUserAdvanced.cmake if you want to change the target directory for the documentation you are about to build.

To build the documentation, you also need to install some Python packages (the Sphinx theme and extensions). These packages are listed in doc/rst/requirements.txt and can be installed via:

$ python -m pip install -r doc/rst/requirements.txt

After configuring and building GMT from source, you can then build the GMT documentation using the following commands within the build directory:

dvc pull
cmake --build . --target docs_depends     # Generate images included in the documentation
cmake --build . --target optimize_images  # Optimize PNG images for documentation [optional]
cmake --build . --target docs_man         # Build UNIX manual pages
cmake --build . --target docs_html        # Build HTML manual, tutorial, cookbook, and API reference

To install the UNIX manpages and html documentation into the specified location (along with the gmt executable, library, development headers and built-in data), use:

cmake --build . --target install

Note

  • Refer to the file admin/bashrc_for_gmt for useful aliases for building the documentation.

  • pngquant is needed for optimizing images.

Contributing an animation

The animations are built from the scripts in doc/examples/anim*/. To add a new animation:

  • Open an issue with your idea for a new animation. It is best to get some feedback on your idea before starting work on the animation. If you do have an animation already made, you can share it as part of the new issue.

  • Create a new script doc/examples/anim??/anim??.sh, where ?? is the number of the new example. Be sure to follow the style of the existing animations, including using #!/usr/bin/env bash and including the purpose, list of modules and unix programs used, and any relevant notes. Use enough comments in your script to make it easily interpretable.

  • Create a new ReStructured Text document doc/rst/source/animations/anim??.rst, where ?? is the number of the new example. Follow the same format as the other anim??.rst files, including the ReST target .. _anim??: at the top, a title, and a description of the animation.

  • Add a directive that will include the source code in the built documentation in doc/rst/source/animations/anim??.rst:

    .. literalinclude:: /_verbatim/anim??.txt
  :language: bash

  • Add a placeholder .. youtube:: directive to the doc/rst/source/animations/anim??.rst file:

    ..  youtube:: Pvvc4vb8G4Y
  :width: 100%

  • Add a placeholder gallery item to the end of the list of animations in doc/rst/source/animations.rst:

    .. youtube:: Pvvc4vb8G4Y
  :width: 100%

  :doc:`/animations/anim??`

  • Submit a pull request with your new animation. Please be sure to follow the pull request template and include the built animation in the pull request or provide a link to the built animation.

  • If the pull request is approved, one of the GMT maintainers will build the animation, upload it to the Generic Mapping Tools YouTube channel, and update the links to the YouTube video in doc/rst/source/animations/anim??.rst and doc/rst/source/animations.rst.

Contributing Code

The source code for GMT is locating in the src/ directory. When contributing code, be sure to follow the general guidelines in the pull request workflow section.

Code Style

When modifying or submitting new source code, make sure that your code follows the GMT code style. Use the other functions/files in the src/ directory as a basis. Here are some specific guidelines:

  • Use tabs, rather than spaces, for indentation.

  • Try to split lines at ~120 characters.

Testing GMT

GMT ships with more than 1000 tests to make sure that any changes won’t break its functionality. In addition to the tests located in the test/ directory, GMT tests all the plots included in its documentation. The documentation tests are located in the doc/scripts/ and doc/examples/ directories. The majority of GMT tests are plot-based, with each test requiring a bash script for generating the plot and a reference PostScript file. These tests pass if the difference between a new plot generated using the test script and the reference PostScript file is less than a defined threshold. Other tests compute grids, tables, or other output, with the test passing if a suitable comparison is made against a reference case.

Tests that are known to fail are excluded by adding # GMT_KNOWN_FAILURE anywhere in the test script. Tests that require a larger tolerance than the default RMS threshold are managed using GRAPHICSMAGICK_RMS = <RMS> in the test script. These tests are tracked in GitHub issue #2458.

Managing Test Images Using Data Version Control (dvc)

As the baseline images are large blob files that can change often, it is not ideal to store them in git. Instead, we use data version control (dvc) to track the test images, which is like git but for data. dvc stores the hash (md5sum) of a file or an md5sum that describes the contents of a directory. For each test test/<module>/*.sh that generates a .PS file, there is a baseline image file in test/baseline/<module>/ that is compared to the test result using GraphicsMagick. Each of the directories test/baseline/<module> are tracked by dvc using the file test/baseline/<module>.dvc. This file contains the hash of a JSON .dir file stored in the .dvc cache. The .dir file contains information about each tracked file in the directory, which is used to push/pull the files to/from remote storage. The test/baseline/<module>.dvc files are stored as usual on GitHub, while the .PS files are stored separately on the dvc remote at https://dagshub.com/GenericMappingTools/gmt.

Setting up your local environment for dvc

  1. Install dvc

  2. If you will need to push baseline images to the remote, ask a GMT maintainer to add you as a collaborator on DAGsHub.

  3. If you will need to push baseline imaged to the remote, set up authentication for the DVC remote.

Pulling files from the remote for testing

To pull or sync files from the dvc remote to your local repository, the commands are similar to git:

dvc status  # should report any files 'not_in_cache'
dvc pull    # pull down files from DVC remote cache (fetch + checkout)

Once the sync is complete, you should notice that there are images stored in the test/baseline/<module> directories (e.g., test/baseline/api/api_matrix_as_grid.ps). These images are technically reflinks/symlinks/copies of the files under the .dvc/cache directory. You can now run the test suite as usual.

Running tests

First, pull any baseline images stored in the DAGsHub repository using dvc:

dvc pull

After configuring CMake and building GMT, you can run all the tests by running this command in the build directory:

cmake --build . --target check

You can also run ctest commands in the build directory. Below are some common used ctest commands.

  • Run all tests in 4 parallel jobs:

    ctest -j 4

  • Re-run all failing tests in previous run in 4 parallel jobs:

    ctest -j 4 --rerun-failed

  • Select individual tests using regexp with ctest:

    ctest --output-on-failure -R ex2[3-6]

Note

Refer to the file admin/bashrc_for_gmt for useful aliases for running the tests.

Reviewing test failures

There are several tests that are “known to fail” for GMT. Unless the GMT_ENABLE_KNOWN2FAIL variable is set when configuring CMake or setting up ConfigUserAdvanced.cmake, these tests are excluded when running ctest using the instructions provided in the Running tests section. Therefore, you should expect all tests to pass unless something new is broken.

Information about failing tests is produced in test/fail_count.txt inside the build directory. For plot-based tests, the subdirectories test/, doc/scripts/, and doc/examples/ inside the build directory contain folders for each failing test. For plot-based tests, the directory associated with each failing tests contains a gmtest.sh script, a gmt.conf file, an alias to the test script, a PostScript file and PDF document generated by the test script, and a PNG image that shows differences between the reference plot and new plot in magenta. In addition to these files, running the failing tests with verbose output can be helpful for evaluating failures:

ctest --rerun-failed --verbose

Updating reference plots for tests

Pull requests should avoid needing to change PostScript files in the test/baseline/, doc/scripts/images/, and doc/examples/images/ directories. However, if this is unavoidable, new PostScript reference files can be generated using the following steps:

  • Run dvc pull to ensure that you have the latest versions of the images.

  • Run ctest -R <test-script-name> in the build directory after following the building guide, the setting up your environment instructions, and the running tests instructions.

  • Copy the modified PostScript file from the appropriate subdirectory within build/test/, build/doc/scripts/, or build/doc/examples/ to test/baseline/<module>, doc/scripts/images/, or doc/examples/images/ respectively.

  • Run the tests to ensure that the failing tests now pass.

  • Run dvc diff to check that modified files are in the correct directory.

  • Add the modified images to dvc using dvc add test/baseline/<module>/<newplot.ps>, dvc add doc/scripts/images/<newplot.ps>, or dvc add doc/examples/images/<newplot.ps> depending on the type of test modified. RUn one dvc add command per updated PostScript plot.

  • Check that the .dvc file was updated by running git status.

  • Stage the modified .dvc files in git using git add test/baseline/<module>/<newplot.ps>.dvc, git add doc/scripts/images/<newplot.ps>.dvc, or git add doc/examples/images/<newplot.ps>.dvc, again per updated file.

  • Commit the changes using git commit.

  • Open a pull request on GitHub with your changes.

  • Push the new images to the DAGsHub repository using dvc push. Optionally, use dvc status --remote origin first to query the diff between your local environment and the remote repository.

Adding new tests

If you are fixing a bug or adding a new feature, you should add a test with your pull request. Most of the tests are image based and compare a result against a reference PostScript file using GraphicsMagick.

To add a PostScript based test (e.g., box.sh):

  • Create a new shell script in the subdirectory under test/ that corresponds to the module you are testing. The name of the shell script should be descriptive and unique.

  • Include #!/usr/bin/env bash and a short description of the test at the top of the script.

  • Add the content of the script that will create a PostScript file (here just called <newplot.ps>). Some general guidelines:

    • Use as small a dataset as possible. See the GMT server cache for some example datasets that can be used.

    • Keep the script as simple as possible, with as few commands and options as needed to test the feature, enhancement, or bug fix.

    • Minimize the size of the resultant PostScript file as much as possible.

  • Run the tests using the instructions in the running tests section.

  • Check that the new PostScript file in build/test/<module> or build/doc/scripts/ is as-expected.

  • Copy the new PostScript file from the appropriate subdirectory within build/test/, build/doc/scripts/, or build/doc/examples/ to test/baseline/<module>, doc/scripts/images/, or doc/examples/images/ respectively.

  • Run the tests to ensure that the new test passes.

  • Run dvc diff to check that the new file is in the correct directory.

  • For teh first test of a module, you add the directory via dvc add test/baseline/<module>, dvc add doc/scripts/images, or dvc add doc/scripts/examples. For later addition you do so per file, e.g. dvc add test/baseline/<module>/<newplot.ps>, dvc add doc/scripts/images/<newplot.ps>, or dvc add doc/scripts/examples/<newplot.ps> depending on the type of test modified.

  • Check that the .dvc file was updated by running git status.

  • Add the modified .dvc file to git using git add test/baseline/<module>/<newplot.ps>.dvc, git add doc/scripts/images/<newplot.ps>.dvc, or git add doc/examples/images/<newplot.ps>.dvc.

  • Commit the changes using git commit.

  • Open a pull request on GitHub with your changes.

  • Push the new images to the DAGsHub repository using dvc push. Optionally, use dvc status --remote origin first to query the diff between your local environment and the remote repository.

To add a non-PostScript based test (e.g., gmean.sh):

  • Create a new shell script in the subdirectory under test/ that corresponds to the module you are testing. The name of the shell script should be descriptive and unique.

  • Include #!/usr/bin/env bash and a short description of the test at the top of the script.

  • Structure the test so that it produced both a reference file with the expected output (e.g., using echo or cat) in a file answer.txt (for a text-based case) and the test output from gmt in a file result.txt.

  • Add a diff` command that will compare the ``result.txt and answer.txt files and create a file fail if the files do not match (e.g., diff -q --strip-trailing-cr answer.txt result.txt > fail).

  • Check that your new test works using the instructions in the running tests section.

Debugging GMT

Guides for debugging GMT are provided in the Debugging GMT section of the GMT documentation.