Skip to content

Commit

Permalink
contributing: Improve where doc is located (#2535)
Browse files Browse the repository at this point in the history 
* Move C API doc compilation from readme.
* Move compilation intro to the end of contributing file.
* Add subsection about testing.
* Move intro to an about section.
* Emphasize source code contributions in the contributing file in the repo.

Co-authored-by: Veronica Andreo <veroandreo@gmail.com>
  • Loading branch information
@wenzeslaus @veroandreo
wenzeslaus and veroandreo committed Aug 28, 2022
1 parent ed30091 commit 77121d9
Show file tree
Hide file tree
Showing 2 changed files with 76 additions and 88 deletions.
122 changes: 73 additions & 49 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -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
<https://grass.osgeo.org/get-involved/>.
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 <https://grass.osgeo.org/get-involved/>.

## Changing code and documentation

Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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
<http://trac.osgeo.org/grass/wiki/Submitting>.

### 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):
Expand Down Expand Up @@ -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.
Expand All @@ -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 <https://trac.osgeo.org/grass/wiki/HowToGit>

## 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.
42 changes: 3 additions & 39 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -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 (<http://www.doxygen.org>) and optionally
Graphviz dot (<http://www.research.att.com/sw/tools/graphviz/>).

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

0 comments on commit 77121d9

Please sign in to comment.