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.

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

Further reading ¶

• Git Cheatsheet: ​http://ndpsoftware.com/git-cheatsheet.html#loc=workspace; (click on a field to see the related git commands)