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 a single commit ¶

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

# switch to branch
git checkout releasebranch_7_6

# first update local repo 
git pull origin releasebranch_7_6 --rebase

# now backport the commit (edit conflicts if needed)
git cherry-pick the_sha1_sum

# push backport 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