prepack
prepack copied to clipboard
"Refactor" how we maintain documentation on PPxxxx diagnostics codes
We currently issue new PPxxxx numbers ad hoc, and maintain wiki pages for them. This is problematic for a number of reasons:
- Wiki pages cannot be edited by the general public, but only Prepack team members
- There's a race when issuing new PPxxxx numbers, as the PRs are disconnected from editing wiki pages
- As a result, discrepancies have crept in in the past, see e.g. #2439
Proposal:
- Migrate all PPxxxx wiki pages to files in a new directory website/diagnostics/en-US
- Have a new file website/diagnostics.html which links to all the individual diagnostics issues
- Consider generating this file with some script that can be run from the scripts/publish-gh-pages.sh script
- Use some on-the-fly markdown processor in JavaScript to render the individual files in the website/diagnostics directory
- (Nice to have) write some kind of linter that ensures that every mention of PPxxxx has an associated file in the website/diagnostics directory
Advantages:
- Races/conflicts between allocating the same new PPxxxx number will be detected before a PR can land
- Diagnostics help text will get reviewed as part of a PR
- Non-prepack team members can contribute diagnostics help
- It will be way easier to ensure that PPxxxx actually have documentation (ideally in an automated fashion with some kind of linter)
If we make the website the source of truth for compiler diagnostics, we should probably either migrate the information from the wiki to the website or figure out if opensource team has a bot that could update the wiki from the repo/website.
One possible concern for this is that our website would either have to update whenever we land a change adding a new error (making it out of sync with npm version bumps) or we would not be able to access the website version of the documentation until the next weekly release.