facebookarchive/prepack

"Refactor" how we maintain documentation on PPxxxx diagnostics codes

Open

#2.440 geöffnet am 17. Aug. 2018

Auf GitHub ansehen
 (1 Kommentar) (0 Reaktionen) (0 zugewiesene Personen)JavaScript (520 Forks)batch import
help wantedrefactoringwebsite

Repository-Metriken

Stars
 (14.268 Stars)
PR-Merge-Metriken
 (Keine gemergten PRs in 30 T)

Beschreibung

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)

Contributor Guide