Session idea: PR Preview

[marcoscaceres]

We should have a session on:

• What is PR Preview?
• When is it useful + navigating around changes
• how to I set it up for my repo?
• dealing with rare preview issues.

cc @tobie

[xfq]

Do we also need to write about other ways to preview a pull request?

Because PR Preview is relatively simple, it does not meet the needs of some groups, and some groups use tools like Netlify/Vercel to preview pull requests of specs.

[marcoscaceres]

We could definitely show alternatives and limitations. Would be interested to hear about those, as I've personally not run into significant issues (apart from in monorepos, which I personally think we should discourage as best practice for spec development).

[xfq]

I agree that PR Preview is a very useful tool, but I would like to write about some of the issues I personally encountered for your reference:

• PR Preview does not support multiple input sources (as for whether monorepos should be discouraged/recommended, we can probably discuss it in a separate issue, but CSS, i18n, Web Bluetooth, EPUB, WICG, and many other W3C groups already have repos with multiple ReSpec/Bikeshed sources)
• It does not support copying images and spec-specific stylesheets/scripts into the preview. For some documents, this is very important.
  • And if the editor only modifies files like images, the reviewer of the pull request cannot preview the document (unless they manually use services like https://raw.githack.com/).
• If the document is too long, PR Preview will time out (maybe it's a Spec Generator issue)
• There are some specs that do not use ReSpec/Bikeshed, and some repos are not used for spec development but contain a static website (PR Preview works for vanilla HTML, if the repo uses a static site generator like Jekyll, it may not be supported)

[tobie]

• PR Preview does not support multiple input sources

That’s a know issue tracked here: tobie/pr-preview#18. I’m happy to take a pull request for it or funding.

• It does not support copying images and spec-specific stylesheets/scripts into the preview. For some documents, this is very important.
  • And if the editor only modifies files like images, the reviewer of the pull request cannot preview the document.

Support for images is tracked here: tobie/pr-preview#6

I don’t think support for other resources has been requested before. Would you mind adding it to the issue or filing a new issue for it?

I’d also happily take a pull request for this.

• If the document is too long, PR Preview will time out (maybe it's a Spec Generator issue)

Could you please file an issue with Spec Generator for this?

• There are some specs that do not use ReSpec/Bikeshed, and some repos are not used for spec development but contain a static website

I feel like this is mostly out of scope unless someone find a clever way to integrate with something like Netlifly’s build service.

[xfq]

Thank you for your reply, Tobie!

I don’t think support for other resources has been requested before. Would you mind adding it to the issue or filing a new issue for it?

Added tobie/pr-preview#6 (comment) and tobie/pr-preview#87

Could you please file an issue with Spec Generator for this?

Filed w3c/spec-generator#396

[marcoscaceres]

Raising awareness of the tools might also help us raise funding to address any shortcomings.