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

First [https://github.com/OSGeo/grass fork the GRASS GIS repo] in the !GitHub UI to `your_GH_account`.

=== Workflow for core developers ===


''- to be discussed which way -''

Add: https://help.github.com/en/articles/connecting-to-github-with-ssh

One time only:
{{{
# ("origin" points to your fork repo)
git clone git@github.com:your_GH_account/grass.git

cd grass/
git remote add upstream git@github.com:OSGeo/grass.git
git remote -v

~~# Or: ("origin" points to original repo: can be dangerous!)~~
~~git clone git@github.com:OSGeo/grass.git~~
~~git remote add your_GH_account git@github.com:your_GH_account/grass.git~~
}}}

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.

=== Workflow for external contributors ===

- to be discussed: is this needed at all? Maybe above part is enough -

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

You clone the GRASS GIS repo and add the fork as an additional remote (or the other way around), this makes merging changes from the GRASS GIS repo easier.

{{{
# create fork via GitHub Web interface

# checkout your the osgeo repo
git clone https://github.com/OSGeo/grass.git

# go to repo dir
cd grass

# add your fork as another remote
git remote add fork https://github.com/<your_GH_account>/grass.git

# change the push URL for your fork to SSH if you have it set up
git remote set-url --push fork ssh://git@github.com/<your_GH_account>/grass.git

# all steps see above, core dev section (branch, edit, commit)
...

# push feature branch to your own fork repo of GRASS GIS

git push fork <feature-branch>

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

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

What is missing above is how you actually update the repo with changes in OSGeo repo master branch.

Alternative is to clone your fork and add osgeo as another remote ("option 2" - "clone fork" as opposed to "clone osgeo"). This would be 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.
== 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 upstream
git rebase upstream/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.

How to accept PR:

-- to be discussed --

* Merge pull request

OR 

* Squash and merge

... based on PR nature.
== 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