Refactor IDE build guidelines

[fstasi]

BUILDING.md file is confusing, partial, and somehow outdated. Also, the current instructions are split between the root and the doc directories, which makes the whole documentation fuzzy and confusing for new comers

A more standard CONTRIBUTING file should definitely be a better choice, along with a well defined architecture of the documents, so that the main CONTRIBUTING file can point to other documents when specific issues needs to be addressed.

Notes

• Existing assets
  • https://github.com/arduino/arduino-ide#readme
  • https://github.com/arduino/arduino-ide/blob/main/BUILDING.md
  • https://github.com/arduino/arduino-ide/blob/main/arduino-ide-extension/README.md
  • https://github.com/arduino/arduino-ide/tree/main/docs
  • https://github.com/arduino/arduino-lint/blob/main/docs/CONTRIBUTING.md

To do

• [ ] Reduce content duplication between CONTRIBUTING.md and the root readme. The root readme should only make a brief mention of these subjects, then link to CONTRIBUTING.md for the details
• [ ] Make sure all content is discoverable
  • The arduino-ide-extension/README.md content seems easy to overlook (It took me two years to notice it). It might make sense to separate the documentation in this way, but if so there must be links between the documents
• [ ] Move documentation content out of arduino-ide-extension/README.md?
  • It seems like there is already a lot of content there, and likely even more is needed. So it might be better to have the readme provide the overview, then move the rest to individual documents under a docs subfolder, linking to there from the readme.
• [ ] Document the i18n sync procedure
  • This is a very frequent task for contributors, necessary to get a passing CI run (related).
  • It might also be worth providing an overview of the whole system (outline in PM here). This information is not needed by community contributors, but the maintainers do need to merge the Transifex pull PRs so it is relevant to the repository. There is currently a folder dedicated to internal documentation: https://github.com/arduino/arduino-ide/tree/main/docs/internal
• [x] Remove the release docs.
  • Even though I support hosting such documents in a public repository, the maintained release procedure documentation is the one on Confluence, and having two documents is harmful.
  • Resolved by the migration of the Confluence doc to GitHub: https://zube.io/arduino/tooling-team/c/13039

Related

• https://github.com/arduino/arduino-ide/pull/791#issuecomment-1031332524
• https://arduino.slack.com/archives/C01S67MJFGC/p1653401933054349
• https://zube.io/arduino/tooling-team/c/12557

[per1234]

PR: https://zube.io/arduino/tooling-team/c/13059