How to contribute to GRASS GIS

Contributions to GRASS are most welcome. There are a number of ways that you can contribute to help make GRASS a better GIS system. Perhaps the most important way to contribute is to write high-quality code for solving old and new problems, and to make your code freely available for others to use. But not everybody is able to program. Still you can help!

Power users

Documentation: If you see manual pages or other documents which are outdated, grammatically incorrect, too short, lacking examples, etc. please don't hesitate to send revised text segments (preferably in HTML) to one of the developers or the related mailing list. Please also contribute to the wiki, improving documentation, providing examples... The best method for submitting changes is via a patch to the trac system (see below).

GRASS Usage: Subscribe to the ​mailing list and answer questions where you have gained some knowledge (and everybody knows something!).

Code developers

For inspiration, we have a wish-list of projects and feature requests. Just pick a task from the list. It may be a good idea to send a small posting to the ​GRASS developers mailing list to announce your activities (maybe someone will join you!). Please read how to write source code. We appreciate if you can fix ​bugs etc.

The Trac ticket system is the best way to submit your code contributions if you don't have write access to SVN, and (even for those with write access) the preferred way to submit more radical changes for general review. See for example trac ticket #33.

• Submit your code and documentation patches ​here.
• ​How to create a patch - they should be generated versus the latest development ("master" in GitHub).

Code quality: Check your code according to GRASS GIS Submitting rules and guide list.

What else: see ​development collection (to be moved here)

Procedure for gaining GRASS repositories write access

To enhance code quality and security, a procedure has been established to control and grant GRASS repositories write access. In general, write access must be requested and is not automatically assigned. Any code submission must be compliant with the GRASS submission rules.

Write access to the GRASS core repository

The typical process for new developers to gain full write access to the ​core GRASS repository is that for some mentorship period they send patches to the grass-dev mailing list (or the trac system) for existing old timer developers to review and commit. Full Git access generally happens when the mentor has seen enough pull requests that they trust the person's code (committing it unchanged) and eventually get bored reviewing & rubber stamping all their pull requests. It is assumed during this period that a track record of trust will be established via participation on the grass-dev mailing list. At some point the mentor nominates the new developer on the PSC mailing list for full write access, and a vote happens.

• In general, the ​GRASS Project Steering Committee is responsible for granting Git write access to contributors (as defined in RFC1).
  • The new developer must read and abide by the document Legal aspects of code contributions (RFC2).
  • An email must be sent to the ​GRASS-PSC mailing list by the new developer stating that RFC2 was read and accepted. This requires ​subscription to the PSC mailing list. After a period of evaluation, Git write access may be granted and is set up in the GitHub authentication system (see below).

Write access to the GRASS addons repository

Rationale:

Write access to the ​Addons repository is much less rigorous than to the core source code repository. It is in effect an incubation area, both for new code and new developers. Write access does not require the full vote of the GRASS-PSC, just the support of one mentor and adherence to our RFC2 document, which guarantees that the code is license-compatible with the rest of GRASS. As opposed to write access to the Main repository, write access to the Addons repository is typically initiated by the new contributor. Overall:

• We invite and encourage users who write GRASS add-on code to host it in our grass-addons repository. We do so because:
  • Community building: It gets people involved and educated - contributing to the main GRASS code uses the exact same website, software, and commands. Thus the trip from contributor to full developer requires a minimum of training.
  • Archival: After some years it is common that people move on, then private websites fade away and the code is lost. The code will be widely backed up and if the main source code ever moves, all the addons will move with it in parallel.
  • Guaranteed license: From the start all code there is licensed under the GPL (or compatible), so all can use the content there without worry, and mature modules may be promoted into the main GRASS code as needed.
  • Caretaking: In years to come others may easily contribute bug fixes and upgrades if a flaw is found or the GRASS API changes.
  • Infrastructure: Ability to take advantage of the git history including bug tracker. (these are really quite good things)
• ​GRASS developers with write access can grant repository write access to contributors (you may contact an active developer, see grass-dev mailing list archive). The selected developer is a sort of "sponsor/mentor" for the requester.

Procedure:

• The requester needs to obtain GitHub account at ​https://github.com/join
• The requester has to read and abide by the document Legal aspects of code contributions (RFC2).
• The request needs to be sent to the GRASS-PSC mailing list, stating that RFC2 was read and accepted (ideally also suggest a mentor among the developers). As only subscribers are allowed to post to OSGeo mailing lists, this requires ​subscription to the mailing list for that time. For fast service you should provide your GitHub username in this email (see below).
• After a period of evaluation, Git write access may be granted and is set up in the GitHub authentication system (see below).
• New commands stored in the GRASS Addons repository should be also added as link to the ​Wiki list of tools and placed in the appropriate directory hierarchy.

Setting up your write access after acceptance

Once the git repo access is granted, the requester's GitHub ID will be enabled by either the GRASS-PSC chair (currently Markus Neteler) and other core developers. Then clone the source code from GitHub.

Important: Contributions have to follow the Submitting code rules.

Then what?

• If you contribute own code: See Submitting - GRASS GIS Addons and ​CONTRIBUTING
• If you want to modify existing code: Get the source code and Happy hacking :)
• If you want to suggest changes or a source code patch, please submit the change as "diff" and not the full modified file. See HowToGit Creating local diffs
• Consider to subscribe to the ​grass-commit mailing list which distributes GRASS-git commit differences for real-time code review.

Coding standards and code style

Check your code against the rules defined in the document Submitting. This ensures a smooth integration into the standard GRASS GIS code base and avoids portability problems.

And after submission of an Addon?

• Users can install it with G7:g.extension or the addon manager in the graphical user interface
• The manual page will automatically appear here: ​http://grass.osgeo.org/grass7/manuals/addons/ (if you followed the coding standards and when you added it in the parent directory's Makefile)
• Enjoy!