How to contribute to GRASS GIS development

GRASS GIS is a powerful tool for spatial data analysis with robust raster, vector, and geospatial processing capabilities. Whether you’re interested in ecosystem modeling, hydrology, or image processing, this open source platform has a lot to offer. And with a built-in temporal framework and Python API, you can leverage its power for advanced time series analysis and scalable geospatial programming.

The core of GRASS GIS consists of libraries, tools, and a graphical user interface (GUI), all of which are continually improved by a dedicated community of volunteers. If you’re excited to contribute, you’ve come to the right place!

Getting started with development

Here is how to get started contributing to GRASS GIS with a focus on Python and the C API by reviewing the existing documentation.

Contributing to GRASS GIS: An overview

Before diving in, familiarize yourself a bit with the contribution process:

• Contribute to GRASS GIS core
• Explore developer resources
• Check out the contribution guide

Set up your development environment

• Install GRASS GIS from source on your machine by following the operating specific installation guides. Here some pages:
  • Linux:
    • Alpine, Arch, CentOS, Debian, Fedora, … | Nix | Ubuntu
  • Windows: MinGW and OSGeo4W (note that compilation will soonish become much easier with the CMake system – in preparation)
  • Mac:
    • MacOS | MacOS M1: Conda
  • Docker:
    • GRASS GIS for Docker
• Brush up on Git, as you’ll need to manage version control for your contributions.
• Set up your favorite IDE with C and Python support, like Visual Studio Code.

Learn the basics

If you already have programming skills in C or Python, you’re off to a good start! GIS users will be familiar with concepts like raster and vector data, but GRASS GIS goes much further. Don’t worry, you’ll catch up quickly.

Explore the codebase

• Clone the GRASS GIS repository from GitHub.
• Browse the code and become familiar with its structure. You can find an architectural overview here.
• When you’re ready to contribute, follow the “fork and pull request” workflow for submitting changes.

And don’t forget to follow the Programming Style Guide to keep everything consistent!

Start small

To ease into development:

• Look for GRASS GIS issues labeled “good first issue“.
• Begin by improving documentation or fixing minor bugs. This will help you familiarize yourself with the process.
• GRASS GIS developers will review your suggested pull request.
• Gradually work up to more complex tasks as your understanding grows.

Writing GRASS GIS addons

Addons may be written in Python, C, or C++ (to some extent also in Fortran, Shell, …).

Python examples:

• have a look at the Cookiecutter GRASS addon template which helps you get started!
• many addons are written in Python, so take a look (addon manual pages)

C examples:

• raster: r.hants
• vector: v.nnstat
• …

C++ examples:

• raster: r.pops.spread
• vector: v.delaunay3d
• …

Just explore the addons repository on GitHub.

Testing changes locally

Once you’ve made some changes, it’s important to test your work to ensure everything runs smoothly.

Build GRASS GIS locally

• Recompile GRASS GIS from source with your updates.

Run the test suite

• GRASS GIS comes with a comprehensive test suite. There are two testing mechanism in place: the gunittest suite and pytest (which is the modern way of testing GRASS GIS). Tests using pytest are written just as any other Python tests, see this pytest example.
• If you find missing tests, take the opportunity to add them!

Manual testing

• Test your changes using both the GUI and command-line interface.
• Ensure everything works as expected and check for side effects.

Debugging

If debugging is needed, then see our Debugging Wiki page.

Code review

• Submit a pull request to the GRASS GIS GitHub repository. Upon submission, automated tests and code analysis tools will be run. Keep an eye on these results to ensure your code passes.
• Make sure to follow best practices and coding standards during this process.

Understanding GRASS GIS

Becoming familiar with the project’s structure and documentation is essential for effective contributions.

Documentation

• Start with the user documentation and the Programmer’s Manual.
• Python developers can explore the GRASS GIS Python library documentation and PyGRASS documentation.
• Examples for Jupyter notebooks are found here
• Python interface through the ctypes binding of the C API of GRASS
• Wiki page describing the temporal framework and its usage

Repository structure

• Learn the layout of the GRASS repository: lib/ for libraries, raster/ and vector/ for core functionality, gui/ for the interface, and more. The architectural diagram can be found here.

Community resources

• Join the community and connect with other developers in the Discourse forum.
• Consider to participate in the annual community sprints to get hands-on experience: Code Sprints. Newcomers are very welcome!

Tutorials and guides

• First of all, examine existing modules to better understand how the system works.
• V. Petras and C. White: Develop Geospatial Workflows and Custom Tools with GRASS GIS
• B. Harmon: Python scripting in GRASS GIS
• mundialis: How to create a GRASS GIS addon
• Interfacing: How to programatically use GRASS GIS with other languages (Wiki pages)
• … and there are many more tutorials!

Opportunities: grants and Google Summer of Code

• Student Grants by the GRASS GIS Project
• Google Summer of Code

Conclusion

Onboarding to GRASS GIS can feel overwhelming at first, but take it one step at a time. Don’t hesitate to ask questions, and remember that the GRASS community is here to support you. Contributing to an open-source project like GRASS GIS is a rewarding experience that will enhance both your programming and GIS skills.

Happy coding!

Blog-post editing history:

• 18 Oct 2024: initial write-up
• 19 Oct 2024: “Set up” section expanded; addons expanded; more tutorials and guides