__[[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 # 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 #(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