Contributing guidelines

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

Important changes:

• committing to "master" (former "trunk") is a no-go and disabled
• hence: you will open a pull request for a change, even being a core developer
  • Rationale: pull requests are the perfect platform to discuss/improve changes before merging.

If you are a core developer:

• the core devs don't go though forks, but create feature branch(es) for changes

If you are an "external" contributor:

• you may fork the GRASS GIS repository and suggest your changes as pull requests.

Workflow for core developers

Here no fork needed but create feature branch(es) on master.

# <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. original GRASS GIS repo master
git push origin $feature_branch_name
# create pull request in GitHub Web interface (the link is 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.

Workflow for external contributors - option 1

• to be discussed -

First fork the GRASS GIS repo in the GitHub web interface.

# create fork via GitHub Web interface

# checkout your fork
git clone $my_for_url

# all steps see above, core dev section
...

# push feature branch to own fork repo of GRASS GIS
git push origin $feature_branch_name   # here: origin is fork repo

# create pull request in GitHub Web interface (the link is shown conveniently in the terminal)

Workflow for external contributors - option 2

• to be discussed -

You clone the GRASS GIS repo and add the fork as an additional remote, this makes merging changes from the GRASS GIS repo easier.

git clone https://github.com/OSGeo/grass.git
cd grass
git remote add github https://github.com/<username>/grass.git
git remote set-url --push github
ssh://git@github.com/<username>/grass.git
...
git push github <feature-branch>

This way origin is the authoritative source for the code, and additional remotes are forks.

Keep your feature branch 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

git fetch origin
git rebase origin/master

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 master.

Backporting to release branches

TODO

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

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