Make Contributing Guidelines

[ES-Alexander]

Our docs and software are currently somewhat difficult to approach for developers who would like to help us improve. With a new docs system it's important to document how it's structured (see #1) and run, but simultaneously it's useful to provide information on how to contribute to the softwares that we're documenting.

Relevant Links

• https://github.com/bluerobotics/software-guidelines
• https://ardupilot.org/dev/docs/contributing.html
• https://github.com/ardupilot/ardupilot#top-contributors / https://github.com/ardupilot/ardupilot#how-to-get-involved
• https://dev.qgroundcontrol.com/master/en/contribute/
• https://github.com/mavlink/qgroundcontrol/blob/master/CONTRIBUTING.md
• https://mavlink.io/en/contributing/contributing.html

[ES-Alexander]

BlueOS workflows auto-build branches and push them to dockerhub provided DOCKER_USERNAME and DOCKER_PASSWORD secrets have been configured, which allows testing modifications directly from the version chooser.

[ES-Alexander]

I'm thinking the ideal/intended development+documentation process is

1. code change PR occurs
2. docs-needed label gets added (if appropriate)
3. relevant docs PR gets submitted to the corresponding -devel-temp docs branch
   • who writes this is situation-dependent*
   • the description of the docs PR should link to the code PR(s) it documents
4. docs PR gets iterated on until it's approved
5. code change PR docs-needed label gets changed to docs-completed
6. code change PR gets merged
7. docs PR gets merged
8. -devel-temp docs branch gets merged into a live docs branch once the corresponding software release gets made

If the code change is time-critical it can be merged before the docs get completed, in which case the docs-needed label is a useful reminder of things that aren't documented yet. The hope is that that shouldn't occur too regularly, and ideally all merged code PRs with docs-needed labels should get documented before the next software release (so the docs are technically never out of date).

*As for who should write the docs, it needs to be someone who knows enough about the feature to do so. We don't have a predetermined responsibility assignment process at this stage, but thinking about it now what makes the most sense to me would be for the responsibility for getting a change documented to lie with the code PR developer, in which case they can either just submit a docs PR and get it reviewed if they're comfortable doing so (especially for straightforward things like minor UI screenshot updates), but if it's something they want help with or want someone else to write then they can ask for that and help provide the information that would be relevant for doing so (and provide reviews as relevant of the docs that get written).

[ES-Alexander]

For reference, some Cockpit-specific docs building instructions are here