make-contributing-easy.md

order	5

Make contributing easy

Requirements

The codebase MUST have a public issue tracker that accepts suggestions from anyone.

Examples

• GitHub Issues like https://github.com/publiccodenet/standard/issues
• Self-hosted Gitea Issues
• (add a good gitlab example)
• Tasks in Phabricator

The documentation MUST link to both the public issue tracker and submitted codebase changes, for example in a README file.

In many platforms, like GitHub, GitLab, Gitea etc. these links are automatically provided in the interface. If you don't use the features of the platform, for example if you have a separate issue tracker, then you must provide these links.

Resources

• Instructions for adding a README file on GitHub. This is linked as part of a repo's community profile.

Further reading

• 18Fs Open Source Guide on READMEs
• Jesse Luotos README best practices
• READMEs for GOV.UK applications

The codebase MUST have communication channels for users and developers, for example email lists.

Preferably, anyone should be able to join these and start discussing without requiring an invite or other manual intervention.

Tools

Mailing lists

• Mailman

Chat

• RocketChat
• Mattermost
• Matrix
• Gitter
• Zulip
• IRC

Fora

• Discourse
• Github Discussions

Video

• Jitsi
• BigBlueButton

Audio

• Mumble

Examples

• FixMyStreet community page with multiple options
• OpenZaak mailing list (Mailman/Postorius/Hyperkitty)
• CivicTech Sweden (matrix)
• Publiccode.yml forum (GitHub discussions)

The codebase MUST include instructions for how to privately report security issues for responsible disclosure.

Resources

• Instructions for adding a SECURITY file on GitHub. This is includes a minimal template and can be used to set up a 'report a vulnerability' button. It's also linked as part of a repo's community profile.

Examples

• OpenZaak SECURITY
• Verdaccio SECURITY

Examples

The documentation MUST include instructions for how to report potentially security sensitive issues.