Skip to content
This repository has been archived by the owner on Feb 12, 2022. It is now read-only.

"Refactor" how we maintain documentation on PPxxxx diagnostics codes #2440

Open
NTillmann opened this issue Aug 17, 2018 · 1 comment
Open

Comments

@NTillmann
Copy link
Contributor

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. PP0038 used multiple times with different meanings #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)
@cblappert
Copy link
Contributor

cblappert commented Aug 17, 2018

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.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

2 participants