facebookarchive/prepack

"Refactor" how we maintain documentation on PPxxxx diagnostics codes

Open

#2,440 opened on 2018年8月17日

GitHub で見る
 (1 comment) (0 reactions) (0 assignees)JavaScript (520 forks)batch import
help wantedrefactoringwebsite

Repository metrics

Stars
 (14,268 stars)
PR merge metrics
 (30d に merged PR はありません)

説明

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)

コントリビューターガイド