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