Contributing guidelines

The development workflow changes notably after ​migration from Subversion to Git (GitHub).

The repo is here: ​https://github.com/OSGeo/grass

Important changes:

• direct committing to "master" (former "trunk") is a no-go and disabled
• hence: you will create a feature branch and open a pull request for a change
  • Rationale: pull requests are the perfect platform to discuss/improve changes before merging.
  • also applies to core developers (to be discussed)

Workflow

• fork the GRASS GIS repository, and create feature branch(es) with the changes, and suggest your changes as pull requests.

Workflow for core grass repository

- to be discussed -

First ​fork the GRASS GIS repo in the GitHub UI to your_GH_account. This is the same as what GitHub documentation suggests. See: ​Fork a repo and ​Syncing a fork in GitHub help.

Note: add SSH key, see ​GitHub documentation.

One time only:

# "origin" points to your fork repo - IMPORTANT
git clone git@github.com:your_GH_account/grass.git

# add "upstream" remote
cd grass/
git remote add upstream git@github.com:OSGeo/grass.git

git remote -v
# you should see something like
origin	  git@github.com:your_GH_account/grass.git (fetch)
origin	  git@github.com:your_GH_account/grass.git (push)
upstream  git@github.com:OSGeo/grass.git (fetch)
upstream  git@github.com:OSGeo/grass.git (push)

Working with git:

# <make local source code changes>
vim ...

# fetch all branches from all remotes
git fetch --all

# list existing branches
git branch -a

# create new local branch (pick a new name for feature_branch_name)
git checkout -b feature_branch_name

# list local changes
git status
git add file1.c file2.py ...
git commit -m 'my change with reasonable explanation...'

# push feature branch to origin, i.e. your fork of the OSGeo/grass repo
git push origin feature_branch_name
# create pull request in GitHub Web interface (the link is then shown in the terminal)

# during PR review phase, make more local changes if needed
git add .
git commit -m 'my second change'
git push origin feature_branch_name
# ..... will be added to existing pull request

NOTE: for different pull requests, simply create different feature branches.

Keep your local source code up to date

[from ​https://github.com/OSGeo/gdal/blob/master/CONTRIBUTING.md#working-with-a-feature-branch]

You may need to resynchronize against master if you need some bugfix or new capability that has been added since you created your branch

# assuming that "upstream" points to OSGeo/grass
git fetch upstream
git rebase upstream/master

# if rebase fails with "error: cannot rebase: You have unstaged changes...", then move your uncommitted local changes to "stash"
git stash
# now you can rebase
git rebase upstream/master
# apply your local changes on top
git stash apply && git stash pop

Continue do your changes and commit/push them (ideally to a feature branch, see above).

Review of pull requests

In the review phase, PRs can be commented and modified.

TODO add more

Merging of pull requests

The CI should run successfully for every commit (chunk of commits in PR to be exact) before it goes into the respective branch.

How to accept PR:

- to be discussed -

• Merge pull request

OR

• Squash and merge

... based on PR nature.

Workflow for grass-addons repository

- to be discussed -

Direct commits are allowed, but you can still use alternatively the same workflow as defined for core repository based on PRs.

One time only:

# "origin" points to your grass-addons repo - no fork needed
git clone git@github.com:OSGeo/grass-addons.git

Work with git:

# <make local source code changes>
vim ...

# list local changes
git status
git add file1.c file2.py ...
git commit -m 'my change with reasonable explanation...'

# assuming that "origin" points to OSGeo/grass-addons
git fetch origin
# IMPORTANT - ALWAYS REBASE IN ORDER TO AVOID NOT NEEDED MERGE COMMITS (!!!)
git rebase origin/master

# push feature branch to origin, i.e. directly to OSGeo/grass-addons repo
git push origin

Switching between branches

For an elegant way of multi-branches in separate directories with only a single repo clone, see

​https://lists.osgeo.org/pipermail/grass-dev/2019-May/092653.html

Backporting to release branches

Preparation

If you checked out the release branch into a separate directory, be sure to have "upstream" enabled as a remote:

git remote -v
# if upstream is missing, execute
git remote add upstream git@github.com:OSGeo/grass.git

Backporting of single commits

git checkout master
# With git log, identify the sha1sum of the commit you want to backport (example: into releasebranch_7_6)

# switch to branch
git checkout releasebranch_7_6
# update
git pull origin releasebranch_7_6 --rebase
# backport the commit
git cherry-pick the_sha1_sum
# push to upstream
git push upstream releasebranch_7_6 

See also ​https://github.com/OSGeo/gdal/blob/master/CONTRIBUTING.md#backporting-bugfixes-from-master-to-a-stable-branch

Backporting of a merged pull request from master

Same as "Backporting of single commits" but with multiple git cherry-pick .... Importantly, in the right order.

TODO: there must be a better way!!

Made a mess? Fix it

Example: mess happened on releasebranch_7_6:

git reset --hard upstream/releasebranch_7_6 
git pull upstream releasebranch_7_6 --rebase

# now all should be clean again

Further reading

• Git Cheatsheet: ​http://ndpsoftware.com/git-cheatsheet.html#loc=workspace; (click on a field to see the related git commands)
• GDAL contributing: ​https://github.com/OSGeo/gdal/blob/master/CONTRIBUTING.md