__[[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 core grass repository ===

'''- to be discussed -'''

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

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 [HowToGit#Workflowforcoregrassrepository 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