Add a project contributor guide #1419
Conversation
per1234
added
topic: documentation
|
Great work @per1234 . However, I was thinking whether such documentation should live along with the code. Why don't we shift this content to the repository's wiki. A great example of a wiki I've seen is of [VS Code] (https://github.com/microsoft/vscode/wiki). The sidebar on the right is clearly demarcated and very easy to navigate. Another aspect that is not captured in the documentation is the Roadmap for Arduino IDE along with a Release philosophy. I think it is very important to lay down the roadmap along with a set of criteria that would lead to the stable release of v2. I believe there is some more work to be done in a few components before a stable release can be brought out. A roadmap stating the activities/ tasks that need to be completed should be put out in the public domain which would focus all our efforts on the same goal. |
|
Thanks for your suggestions @nmzaheer.
I have extensive experience with GitHub Wikis and they are far inferior to using a repository in almost every way. You lose the incredible benefits of the pull request system. Even though a wiki is a Git repository under the hood, it is a strange repository and I don't think anyone ever works in them via a Git clone. So you miss the ability to edit multiple files at once, to work directly on the files with a professional quality text editor, to write proper commits. The one thing of value to GitHub wikis is the ability to allow open editing of the content by anyone. That would not be appropriate with this content. Anyone may propose changes to it, but that proposal must pass through a review process by the maintainers.
If we wanted some navigation, we would set up a MkDocs-based website as we have done with other tooling projects:
GitHub has a nice system for that: https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/about-milestones Adding milestones to issues is much easier than maintaining a bespoke list that would actually be inferior in functionality due to not having the searching, sorting, and categorization features of GitHub Issues. |
+1 for this too. As long as there is a way to track our progress, it would be great. |
Previously, information about project development was stored in a file named BUILDING.md in the root of the repository. That content is hereby moved to the file docs/development.md. This will provide the following benefits: - Broaden the scope of the file to all information related to development rather than building only - Store all documentation content under a single folder instead of randomly putting some in the root and others under docs
Previously, the information about tester builds was mixed in with the documentation about building the project from source. The two subjects are of relevance to two distinct contribution options. Building from source will primarily be done by developers working on the project code base. Tester builds will be used by beta testers and reviewers. For this reason, it doesn't make sense to require beta testers to wade through a lot of development documentation not directly related to their work in order to find the instructions for obtaining tester builds. Likewise, it doesn't make sense to clutter up the development documentation with such information. Moving the information about tester builds to a dedicated file makes it easier for the interested parties to find, and also allows the creation of a comprehensive guide for beta testers without making a negative impact on the development documentation content.
Documentation of how to contribute to the project gives everyone the opportunity to participate, while also reducing the maintenance effort and increasing the quality of contributions. This guide documents the various ways of contributing to the project.
The readme should provide a concise overview of the essential information about the project. Additional details are provided in dedicated documents, so the readme only needs to provide links to that information.
For security reasons, the macOS tester builds generated for PRs from forks are not notarized. Instructions are provided for beta testing under these conditions. Previously, the instructions for bypassing the macOS notarization requirement involved disabling macOS Gatekeeper entirely using the spctl command. These instructions are hereby replaced by an alternative approach, where the restriction is bypassed for the Arduino IDE application alone, via the macOS GUI. The new approach is superior for the following reasons: - More secure due to having limited scope - More accessible due to the use of the macOS GUI
Motivation
Documentation of how to contribute to the project gives everyone the opportunity to participate, while also reducing the maintenance effort and increasing the quality of contributions.
Currently, the ways and processes for contributing to this project are not fully documented, and the existing documentation is somewhat disorganized
Change description
Add a guide documenting the various ways of contributing to the project.
Take advantage of GitHub's "contributing guidelines" feature to increase the visibility of the information to prospective contributors.
Other information
See the rendered content here:
https://github.com/per1234/arduino-ide/blob/contributor-guide/docs/CONTRIBUTING.md
Reviewer checklist