Discrepancy between CI and contributor guidelines

[jugglinmike]

This project's README.md file recommends the use of scripts/build.sh which fails to build the proposal from the tip of the main branch:

$ ./scripts/build.sh

[irrelevant script output elided]

+ bikeshed --die-on=warning spec index.bs
LINE ~2649: No 'dfn' refs found for 'source browsing context'.
[=source browsing context=]
 ✘  Did not generate, due to fatal errors

However, this is more strict than the automated build process, which uses a different value for Bikeshed's --die-on argument. From the logs for the build for the same commit:

$ bikeshed --die-on=fatal spec "index.bs" "index.bs.built.html" 
  LINE ~1008: No 'dfn' refs found for 'active window' that are marked for export.
  [=active window=]
  LINE ~2604: No 'dfn' refs found for 'parent browsing context'.
  [=parent browsing context=]
  LINE ~2618: No 'dfn' refs found for 'child browsing contexts'.
  [=child browsing contexts=]
  LINE ~2649: No 'dfn' refs found for 'source browsing context'.
  [=source browsing context=]
  LINE ~3325: No 'dfn' refs found for 'parent browsing context'.
  [=parent browsing
   context=]
   ✔  Successfully generated, with 5 linking errors

This means that although the main branch is reported as "passing," contributors experience a failure when attempting to build the specification locally.

[whimboo]

Thanks for reporting @jugglinmike! I think that there are two issues here:

1. We should indeed reference the identical calling convention for build.sh in the README
2. We probably have / want to fix those errors

@jgraham do you agree on the second point or are there any limitations that we cannot correctly define those dfn refs?

[jgraham]

Right, so actually what happened here is that the HTML spec made a breaking change and now we need to handle it.

We still want our CI build to die on warnings, but we want the preview build to be generated in spite of warnings.

I suggest we change the README to not refer to the CI script.