doc: GRASS Programming Style Guide

[petrasovaa]

This is an attempt to consolidate and update documentation for code contributors into a style guide:

• The idea is to focus on style and best practices, contributing through GitHub is not described here.
• The source are the files from submitting folder (originally converted from Trac wiki), I tried to extract useful and relevant things, this PR removes those files.
• Another source is @wenzeslaus' workshop on development and best practices
• I kept it as one document right now, but I am open to splitting it up or restructuring it.

I would appreciate any feedback on this. For example I don't have a lot about pylint usage there or best practices in C.

[echoix]

If I recall correctly, there is a special handling for a file named CONTRIBUTING.md, a bit like README files. If we really want to use a file in the doc subfolder, we could create a contributing file and link to the full docs in it.

[veroandreo]

Looks good to me, it covers all aspects simply and concisely including examples :)

[echoix]

If I recall correctly, there is a special handling for a file named CONTRIBUTING.md, a bit like README files. If we really want to use a file in the doc subfolder, we could create a contributing file and link to the full docs in it.

The docs are here: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors

There are multiple paths that GitHub's UI will integrate these contribution guidelines on PRs for new users, or for other users if that document changes since their last contribution.

I think we should take advantage of it instead of inventing our own and being left to make it discoverable by our own too.

Our page looks like this:

https://github.com/osgeo/grass/contribute

[petrasovaa]

If I recall correctly, there is a special handling for a file named CONTRIBUTING.md, a bit like README files. If we really want to use a file in the doc subfolder, we could create a contributing file and link to the full docs in it.

The docs are here: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors

There are multiple paths that GitHub's UI will integrate these contribution guidelines on PRs for new users, or for other users if that document changes since their last contribution.

I think we should take advantage of it instead of inventing our own and being left to make it discoverable by our own too.

The idea with this style guide is to link it from the CONTRIBUTING.md file. That file needs some improvement, but that would be a different PR.

[echoix]

Perfect then

[neteler]

IMHO this should go into G8.4.0, no need to postpone. A nice document!

[wenzeslaus]

This is not published as part of the documentation, so I don't know where this will be visible in the release except release notes (which is nice), but we need this to be in the code for GSoC so we don't have to link a file in a PR.

[wenzeslaus]

Thanks for addressing all the issues.

[mshukuno]

@petrasovaa Thank you for creating the GitHub guide. I am sure it will be helpful to someone like me who uses GitHub but has no experience with team workflows. This "pre-commit" feature is awesome!!

I encountered a problem when I ran pre-commit run black --all-files. I got a message "No hook with id black in stage 'pre-commit" message. I believe the hook id is black-jupyter in pre-commit-config.yaml.

[echoix]

I encountered a problem when I ran pre-commit run black --all-files. I got a message "No hook with id black in stage 'pre-commit" message. I believe the hook id is black-jupyter in pre-commit-config.yaml.

Yep, you are completely right, it was changed a couple months ago. It is the pre-commit equivalent of installing black with jupyter support with pip install black[jupyter] instead of pip install black. (With pip, the brackets are called "extras" and are optional features, delimited by commas, to also install optional packages that enable optional features).

If you want to run on all files, not only files that you are about to commit, I usually use

pip install pre-commit
pre-commit run -a

And that installs and runs on all files.