diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6609fe64f38..0c137d983bc 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,38 +1,10 @@
-# Introduction
-
-GRASS GIS is written in more than one programming language. While most
-of the source code is written in C, about 30% is written in Python. A
-compiler is needed to convert the C/C++ source code into executable
-files ("binaries"). In contrast, Python is an interpreted language that
-can only be executed with Python software.
-
-Now, in order to create an installable binary package from a source
-code package, the so-called "compilation step" is required. While the
-source code consists of thousands of C and Python files (plus HTML
-documentation), the included "makefiles" tell the build system to
-generate binaries from the source code in the correct order, render the
-manual pages, etc.
-
-The way to install the compiler tools and Python depends on the operating
-system. To make this easier, we have collected copy-paste instructions
-for most operating systems in our wiki:
-
-[Compile and install instructions](https://grasswiki.osgeo.org/wiki/Compile_and_Install)
-
# Contributing
-## Contributions other than code
-
-There is more than one way of contributing, see full list at
-.
-In the rest of this document, we will focus on contributions centered
-around the GRASS GIS source code.
-
-## Reporting issues and suggesting features
-
-To report an issue or to suggest features or a change,
-[open an issue](https://github.com/OSGeo/grass/issues/new/choose)
-on GitHub.
+There is more than one way of contributing to GRASS GIS.
+Here we will focus on contributions centered
+around the main GRASS GIS source code.
+You can also report issues, plan new features,
+or explore .
## Changing code and documentation
@@ -49,10 +21,10 @@ GRASS GIS developer mailing list.
* 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 SSH or HTTPS URL):
+* Clone your fork (use HTTPS or SSH URL, here we will use HTTPS):
```
-git clone git@github.com:your_GH_account/grass.git
+git clone https://github.com/your_GitHub_account/grass.git
```
* Enter the directory
@@ -77,20 +49,23 @@ 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)
+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.git (fetch)
upstream https://github.com/OSGeo/grass.git (push)
```
-It is important that "origin" points to your fork.
+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:
```
-git checkout main
+git switch main
```
* Download updates from all branches from the _upstream_ remote:
@@ -106,7 +81,11 @@ git fetch upstream
git rebase upstream/main
```
-### Update if you have local branches
+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:
@@ -121,13 +100,7 @@ git stash
git rebase upstream/main
```
-* Apply your local changes on top:
-
-```
-git stash apply
-```
-
-* Remove the stash record (optional):
+* Get the changes back from stash:
```
git stash pop
@@ -147,10 +120,31 @@ 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 make changes, please follow
+in the local copy of the code. When making changes, please follow
Submitting Guidelines at
.
+### Testing changes
+
+Testing helps to ensure that the changes work well with the rest
+of the project. While there are many different ways to test,
+usually you will want to compile the source code (see below),
+add test code (using _grass.gunittest_ or pytest), and run code
+linters (automated code quality checks).
+
+There is a series of automated checks which will run on your pull request
+after you create one. You don't need to run all these
+checks locally and, indeed, some of them may fail for your code. This is a part of
+the standard iterative process of integrating changes into the main code,
+so if that happens, just see the error messages, go back to your code
+and try again. If you are not sure what to do, let others know in a pull
+request comment.
+
+Note that there are some steps you can do locally to improve your code.
+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):
@@ -179,9 +173,12 @@ git push origin new-feature
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 button to create
+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.
@@ -198,3 +195,30 @@ local _main_ branch in order to get the change you just contributed.
GRASS GIS maintainers use additional workflows besides the one described
above. These are detailed at
+
+## Compilation
+
+More often than not, in order to test the changes, you need to create
+a runnable binary program from the source code,
+using the so-called "compilation step". While the
+source code consists of thousands of C and Python files (plus HTML
+documentation and other files), the included "makefiles" tell the build system to
+generate binaries from the source code in the correct order, render the
+manual pages, etc.
+
+The way to install the compiler tools and Python depends on the operating
+system. To make this easier, we have collected copy-paste instructions
+to install dependencies and compile GRASS source code for most operating systems.
+Please see our dedicated wiki:
+
+[Compile and install instructions](https://grasswiki.osgeo.org/wiki/Compile_and_Install)
+
+## About source code
+
+GRASS GIS is written in more than one programming language, but you need
+to know only the language relevant to your contribution. While much
+of the source code is written in C, a significant portion is written in Python.
+A compiler is needed to convert the C and C++ source code into executable
+files ("binaries"). In contrast, Python is an interpreted language that
+can only be executed with Python software. There is also documentation
+in HTML files and other files in the GRASS GIS source code.
diff --git a/README.md b/README.md
index 062759f7eef..87fbb805800 100644
--- a/README.md
+++ b/README.md
@@ -21,12 +21,14 @@ Launch this repository in Binder and experiment with GRASS's Python API in Jupyt
[![Binder](https://camo.githubusercontent.com/581c077bdbc6ca6899c86d0acc6145ae85e9d80e6f805a1071793dbe48917982/68747470733a2f2f6d7962696e6465722e6f72672f62616467655f6c6f676f2e737667)](https://mybinder.org/v2/gh/OSGeo/grass/main?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fjupyter_example.ipynb)
-## How to get write access here
+## Contributing
In general: you don't really need write access as you can simply open
a [pull request](https://github.com/OSGeo/grass/pulls) to contribute to
GRASS GIS. See [CONTRIBUTING file](CONTRIBUTING.md) for more details.
+How to get write access here
+
Want to become a core developer? See
[Procedure for gaining Git write access](https://trac.osgeo.org/grass/wiki/HowToContribute#WriteaccesstotheGRASScorerepository)
@@ -82,41 +84,3 @@ this issue, clean all the compiled files from the source code:
```
make distclean
```
-
-## How to generate the 'Programmer's Manual'
-
-You can locally generate the [GRASS GIS Programmer's Manual](https://grass.osgeo.org/programming8/).
-
-This needs doxygen () and optionally
-Graphviz dot ().
-
-To build the GRASS programmer's documentation, run
-
-```
-make htmldocs
-```
-
-Or to generate documentation as single html file
-(recommended for simple reading)
-
-```
-make htmldocs-single
-```
-
-This takes quite some time. The result is in `lib/html/index.html`
-which refers to further document repositories in
-
-```
-lib/vector/html/index.html
-lib/db/html/index.html
-lib/gis/html/index.html
-```
-
-The master file is: `./grasslib.dox` where all sub-documents have to
-be linked to.
-
-To generate the documents in PDF format, run
-
-```
-make pdfdocs
-```