__[[TOC]]__

== Contributing guidelines ==

The development workflow changes notably after [https://trac.osgeo.org/grass/wiki/GitMigration#ImplementationofmigrationfromOSGeoSVNandtractoGitHub 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 GRASS GIS git repositories ===

The same procedure is recommended also from [https://github.com/osgeo/grass-addons GRASS Addons repository].
==== Preparation: cloning the repo ====

First [https://github.com/OSGeo/grass fork the GRASS GIS repo] in the !GitHub UI to `your_GH_account`. This is the same as what !GitHub documentation suggests. See: [https://help.github.com/en/articles/fork-a-repo Fork a repo] and [https://help.github.com/en/articles/syncing-a-fork Syncing a fork] in !GitHub help.

Note: add SSH key, see [https://help.github.com/en/articles/connecting-to-github-with-ssh GitHub documentation].

{{{
# "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)
}}}

Similarly for GRASS Addons repository:

{{{
git clone git@github.com:your_GH_account/grass-addons.git
cd grass-addons/
git remote add upstream git@github.com:OSGeo/grass-addons.git
}}}
==== Working with git ====

Note: this requires the "remotes" to be set as shown above.

{{{
# updating from git server: fetch all branches from all remotes
git fetch --all

### a) updating MASTER
# merge updates into local master
git merge upstream/master

# at this point we have reached:
# (HEAD -> master, upstream/master)

### b) updating releasebranch_7_6
# switch to branch
# only once
git checkout -b releasebranch_7_6 origin/releasebranch_7_6
# next time, git checkout releasebranch_7_6

# merge updates into local branch
git merge upstream/releasebranch_7_6

# at this point we have reached:
# (HEAD -> releasebranch_7_6, upstream/releasebranch_7_6)

# update own remote
# - clears "Your branch is ahead of 'origin/master' by XX commits.", and
# - avoids "This branch is XX commits behind OSGeo:master." on GitHub web interface
git push origin master

# list existing branches
git branch -a

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

# <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...'

# 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).


== 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

== Testing pull requests from other contributors in master ==

!GitHub provides command line instructions under each pull request ([https://github.com/OSGeo/grass/pulls "Pulls" tab]). Please check there.

== Fixing bugs in a release branch ==

To directly fix bugs (ideally via feature branch), do

(example: https://github.com/OSGeo/grass/tree/releasebranch_7_8)

{{{
# push to release_branch, we assume it to be checked out

cd releasebranch_78/
# be sure to locally have all updates from server
git fetch --all
git branch --merged 

# create feature branch
git checkout -b r78_fix_xxx

# ... do changes...

git status
git add ...
git commit -m 'useful commit msg...'

# push to feature branch
git push upstream r78_fix_xxx
}}}

Now create the PR in !GitHub UI using the link shown by `git push ...` in the terminal.

**IMPORTANT: switch there to release_branch_X_Y!**

After PR positive review, merge PR in !GitHub.

Local cleanup after successful PR merge:
{{{
# switch to release branch
git checkout releasebranch_7_8

# be sure to locally have all updates
git fetch --all
git branch --merged 

# delete local feature branch as no longer needed
git branch -D r78_fix_xxx 
git fetch --all --prune
git branch -a
}}}

== 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 from master to release branch ===

... assumming that we are in releasebranch_7_8 branch:

{{{
git fetch --all --prune
git rebase upstream/releasebranch_7_8
# get hash from GitHub or git log in master
git cherry-pick <hash>

#(or
#git cherry-pick -m1 hash
#when cherry picking a merge request)

# verify
git show

# push backport to upstream
git push upstream releasebranch_7_8
}}}


=== 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
}}}

== Code review: generate a single diff for a PR with multiple commits ==

To speed up reviewing of a PR with multiple commits by reading a single diff file, you may diff the branch against the branch origin point. For example, if you PR 28 is on local branch pr_28, branched from master, you can do:

{{{
git checkout pr_28

# note: with the three dots, it will only show diffs from changes on your side:
git diff master...
}}}

For more hints, see e.g. this [https://stackoverflow.com/questions/29810331/is-there-a-quick-way-to-git-diff-from-the-point-or-branch-origin Stackoverflow discussion].

== Merging of Pull Requests ==

Rationale: We should try to have clean history and good commit messages. This helps really a lot when you try to understand why something is implemented the way it is.

When a Pull Requests (PR) has multiple commits, the merge commit is more or less mandatory because if you don't have it, you can't use `git revert`.

=== PR with single commit ===

**Proposed**: when a PR only has a single commit, the "merge commit" doesn't offer anything and it can be avoided by rebasing the feature branch:

Workflow: !GitHub > button "Merge pull request" > "Rebase and merge"

Next, you may locally delete the feature branch.

=== PR with multiple commits ===

**Proposed**: it is a good idea to try to squash the accumulated commits in a PR before merging, especially if those are trivial fixes.

As an example, PRxx contains 5 commits. Esp. in case that several commits of them are trivial fixes that only add noise to the history, "squashing" those results in a cleaner history and, among other things, makes it easier to use `git bisect` and `git blame`.

Importantly, not always commits of each and every PR need to be squashed before merging. When extensive changes are being made, it often makes sense to keep them unsquashed (e.g. to make reviewing easier), but trivial fixes should still be squashed to the main commits.

== 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