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

If you are a core developer:
 * the core devs don't go though forks, but create feature branch(es) for changes (to be discussed, see GDAL Contributing.md with forks for all)

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 (to be discussed; GDAL always forks)

{{{
git clone https://github.com/OSGeo/grass
cd grass/

# <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 the respective branch.

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