contributing: move GitHub workflow docs into separate file

CONTRIBUTING.md

@@ -8,122 +8,13 @@ or explore <https://grass.osgeo.org/get-involved/>.
 
 ## Changing code and documentation
 
-This guide covers contributing to the main version of GRASS GIS source
-code which is in the branch called _main_.
-It assumes that you have some very basic knowledge of Git and GitHub,
-but if you don't just go through some tutorial online or ask on the
-GRASS GIS developer mailing list.
+To contribute changes to GRASS GitHub repository, use a
+"fork and pull request" workflow. This [guide](./doc/development/github_guide.md)
+leads you through a first time setup and shows how to create a pull request.
 
 To contribute effectively, please familiarize yourself with our
 [Programming Style Guide](./doc/development/style_guide.md).
 
-### First time setup
-
-* Create an account on GitHub.
-* Install Git on your computer.
-* Set up Git with your name and email.
-* Fork the repository (by clicking the `Fork` button in the upper right corner
-  of the GitHub interface).
-* Clone your fork (use HTTPS or SSH URL, here we will use HTTPS):
-
-```bash
-git clone git@github.com:your_GH_account/grass.git
-```
-
-* Enter the directory
-
-```bash
-cd grass/
-```
-
-* Add main GRASS GIS repository as "upstream" (use HTTPS URL):
-
-```bash
-git remote add upstream https://github.com/OSGeo/grass
-```
-
-* Your remotes now should be "origin" which is your fork and "upstream" which
-  is this main GRASS GIS repository. You can confirm that using:
-
-```bash
-git remote -v
-```
-
-* You should see something like:
-
-```bash
-origin  git@github.com:your_GH_account/grass.git (fetch)
-origin  git@github.com:your_GH_account/grass.git (push)
-```
-
-For the following workflow, it is important that
-"upstream" points to the OSGeo/grass repository
-and "origin" to your fork
-(although generally, the naming is up to you).
-
-### Update before creating a feature branch
-
-* Make sure your are using the _main_ branch to create the new branch:
-
-```bash
-git checkout main
-```
-
-* Download updates from all branches from the _upstream_ remote:
-
-```bash
-git fetch upstream
-```
-
-* Update your local _main_ branch to match the _main_ branch
-  in the _upstream_ repository:
-
-```bash
-git rebase upstream/main
-```
-
-Notably, you should not make commits to your local main branch,
-so the above is then just a simple update (and no actual
-rebase or merge happens).
-
-### Update if you have local changes
-
-If `rebase` fails with "error: cannot rebase: You have unstaged changes...",
-then move your uncommitted local changes to "stash" using:
-
-```bash
-git stash
-```
-
-* Now you can rebase:
-
-```bash
-git rebase upstream/main
-```
-
-* Get the changes back from stash:
-
-```bash
-git stash pop
-```
-
-### Creating a new feature branch
-
-Now you have updated your local _main_ branch, you can create a feature branch
-based on it.
-
-* Create a new feature branch and switch to it:
-
-```bash
-git checkout -b new-feature
-```
-
-### Making changes
-
-You can use your favorite tools to change source code or other files
-in the local copy of the code. When making changes, please follow the
-[Programming Style Guide](./doc/development/style_guide.md).
-
 ### Testing changes
 
 Testing helps to ensure that the changes work well with the rest
@@ -145,57 +36,6 @@ For Python, run `black .` to apply standardized formatting. You can
 also run linter tools such as Pylint which will suggest different improvements
 to your code.
 
-### Committing
-
-* Add files to the commit (changed ones or new ones):
-
-```bash
-git add file1
-git add file2
-```
-
-* Commit the change (first word is the module name):
-
-```bash
-git commit -m "module: added a new feature"
-```
-
-### Pushing changes to GitHub
-
-* Push your local feature branch to your fork:
-
-```bash
-git push origin new-feature
-```
-
-### Pull request
-
-When you push, GitHub will respond back in the command line to tell
-you what URL to use to create a pull request. You can follow that URL
-or you can go any time later to your fork on GitHub, display the
-branch `new-feature`, and GitHub will show you a button to create
-a pull request.
-
-Alternatively, you can explore GitHub CLI tool (_gh_) which allows you
-to do `git push` and create a pull request in one step with `gh pr create -fw`.
-
-### After creating a pull request
-
-GRASS GIS maintainers will now review your pull request.
-If needed, the maintainers will work with you to improve your changes.
-
-Once the changes in the pull request are ready to be accepted,
-the maintainers will usually squash all your commits into one commit and merge it
-to the _main_ branch.
-
-Once the pull request is merged, it is a good time to update your
-local _main_ branch in order to get the change you just contributed.
-
-### Further notes
-
-GRASS GIS maintainers use additional workflows besides the one described
-above. These are detailed at <https://trac.osgeo.org/grass/wiki/HowToGit>
-
 ## Compilation
 
 More often than not, in order to test the changes, you need to create

doc/development/github_guide.md

@@ -0,0 +1,187 @@
+# Guide to contributing on GitHub
+
+This guide covers contributing to the GRASS GIS source,
+specifically to the _main_ branch.
+It assumes that you have some very basic knowledge of Git and GitHub.
+
+## First time setup
+
+1. Create an account on GitHub.
+1. Install Git on your computer.
+1. Set up Git with your name and email.
+1. Fork the repository (by clicking the `Fork` button in the upper right corner
+  of the GitHub interface).
+1. Clone your fork (use HTTPS or SSH URL, here we will use HTTPS):
+
+```bash
+git clone https://github.com/your_GH_account/grass.git
+```
+
+1. Enter the directory:
+
+```bash
+cd grass/
+```
+
+1. Add the main GRASS GIS repository as "upstream" (use HTTPS URL):
+
+```bash
+git remote add upstream https://github.com/OSGeo/grass
+```
+
+1. Your remotes now should be "origin" which is your fork and "upstream" which
+  is this main GRASS GIS repository. You can confirm that using:
+
+```bash
+git remote -v
+```
+
+1. You should see something like:
+
+```bash
+origin  https://github.com/your_GH_account/grass.git (fetch)
+origin  https://github.com/your_GH_account/grass.git (push)
+upstream  https://github.com/OSGeo/grass (fetch)
+upstream  https://github.com/OSGeo/grass (push)
+
+```
+
+For the following workflow, it is important that
+"upstream" points to the OSGeo/grass repository
+and "origin" to your fork
+(although generally, the naming is up to you).
+
+## Update before creating a feature branch
+
+Make sure your are using the _main_ branch to create the new branch:
+
+```bash
+git checkout main
+```
+
+Download updates from all branches from the _upstream_ remote:
+
+```bash
+git fetch upstream
+```
+
+Update your local _main_ branch to match the _main_ branch
+  in the _upstream_ repository:
+
+```bash
+git rebase upstream/main
+```
+
+Notably, you should not make commits to your local main branch,
+so the above is then just a simple update (and no actual
+rebase or merge happens).
+
+## Creating a new feature branch
+
+Now you have updated your local _main_ branch, you can create a feature branch
+based on it.
+
+Create a new feature branch and switch to it:
+
+```bash
+git switch -c new-feature
+```
+
+## Committing
+
+Add files to the commit (changed ones or new ones):
+
+```bash
+git add file1
+git add file2
+```
+
+Commit the change. Write a meaningful commit message (first word is for example
+the tool name):
+
+```bash
+git commit -m "tool: added a new feature doing X"
+```
+
+## Pushing changes to GitHub
+
+Push your local feature branch to your fork:
+
+```bash
+git push origin new-feature
+```
+
+## Creating a pull request
+
+When you push, GitHub will respond back in the command line to tell
+you what URL to use to create a pull request (PR). You can follow that URL
+or you can go any time later to your fork on GitHub, display the
+branch `new-feature`, and GitHub will show you a button to create
+a PR.
+
+Alternatively, you can explore GitHub CLI tool (_gh_) which allows you
+to do `git push` and create a PR in one step with `gh pr create -fw`.
+
+## After creating a PR
+
+GRASS GIS maintainers will now review your PR.
+If needed, the maintainers will work with you to improve your changes.
+
+Once the changes in the PR are ready to be accepted,
+the maintainers will usually squash all your commits into one commit and merge it
+to the _main_ branch.
+
+Once the PR is merged, it is a good time to [update your
+local _main_ branch](#update-before-creating-a-feature-branch) in order to get
+the change you just contributed.
+
+## Further notes
+
+Here we cover common situations and how to deal with them:
+
+### Update if you have local changes
+
+Assumption is you are on the main branch and you are trying to update it.
+If `git rebase` fails with `error: cannot rebase: You have unstaged changes...`,
+then move your uncommitted local changes to "stash" using:
+
+```bash
+git stash
+```
+
+Now you can rebase:
+
+```bash
+git rebase upstream/main
+```
+
+Get the changes back from stash:
+
+```bash
+git stash pop
+```
+
+### Updating your PR from main
+
+Updating your PR from the main branch is often referred to as rebasing a PR.
+It comes into play in case there are changes in the main branch you need to
+incorporate into your (feature or fix) branch before the PR can be merged,
+you need to merge the upstream main into your branch:
+
+```bash
+git fetch upstream
+git merge upstream/main
+```
+
+Git will ask you to edit the merge commit messsage, you can leave the default
+and close the editor. You may run into a conflict,
+in that case you need to resolve it.
+
+### Testing PRs from other contributors
+
+For testing other contributors' PRs, we recommend using
+[GitHub CLI](https://cli.github.com/). To checkout a specific PR, run:
+
+```bash
+gh pr checkout <PR number>
+```