There is more than one way of contributing, see full list at https://grass.osgeo.org/get-involved/. In the rest of this document, we will focus on contributions centered around the GRASS GIS Addons source code.
To report an issue or to suggest features or a change, open an issue on GitHub.
This guide covers contributing to the latest version of GRASS GIS Addons source code which is stored in a branch called grass8. It assumes that you have some very basic knowledge of Git and GitHub, but if you don't just go through some tutorial online or ask on the GRASS GIS developer mailing list.
- Create an account on GitHub.
- Install Git on your computer.
- Set up Git with your name and email.
- Fork the repository.
- Clone your fork (use SSH or HTTPS URL):
git clone [email protected]:your_GH_account/grass-addons.git
- Enter the directory
cd grass-addons/
- Add main GRASS GIS Addons repository as "upstream" (use HTTPS URL):
git remote add upstream https://github.com/OSGeo/grass-addons
- Your remotes now should be "origin" which is your fork and "upstream" which is this main GRASS GIS Addons repository. You can confirm that using:
git remote -v
- You should see something like:
origin [email protected]:your_GH_account/grass-addons.git (fetch)
origin [email protected]:your_GH_account/grass-addons.git (push)
upstream https://github.com/OSGeo/grass-addons.git (fetch)
upstream https://github.com/OSGeo/grass-addons.git (push)
It is important that "origin" points to your fork.
- Download updates from all branches from the upstream remote:
git fetch upstream
- Make sure your are starting with the branch for the latest version, i.e., grass8:
git switch grass8
- Update your local branch to match the one in the upstream repository:
git rebase upstream/grass8
If rebase
fails with "error: cannot rebase: You have unstaged changes...",
then move your uncommitted local changes to "stash" using:
git stash
- Now you can rebase:
git rebase upstream/grass8
- Apply your local changes on top of the updated code:
git stash pop
Now you have updated your local branch, you can create a feature branch based on it.
- Create a new feature branch and switch to it:
git switch -c new-feature
You can use your favourite tools to change source code or other files in the local copy of the code. When making such changes, please follow the general GRASS GIS Programming Style Guide.
- Add files to the commit (changed ones or new ones):
git add file1
git add file2
- Commit the change (first word is the module name):
git commit -m "module: added a new feature"
- Push your local feature branch to your fork:
git push origin new-feature
When you push, GitHub will respond back in the command line to tell
you what URL to use to create a pull request. You can follow that URL
or you can go any time later to your fork on GitHub, display the
branch new-feature
, and GitHub will show you button to create
a pull request.
Some contributors use GitHub CLI which allows them to create the pull request from command line in one step together with pushing the changes to GitHub.
GRASS GIS maintainers or users will now review your pull request. If needed, they will work with you to improve your changes.
Once the changes in the pull request are ready to be accepted, the maintainers will usually squash all your commits into one commit and merge it to the grass8 branch.
Once the pull request is merged, it is a good time to update your local grass8 branch in order to get there the change you just contributed.
GRASS GIS maintainers use additional workflows besides the one described above. These are detailed at https://trac.osgeo.org/grass/wiki/HowToGit
Consider including a unit test suite with your addon. More details in these instructions.