Session idea: PR Preview

marcoscaceres commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

PR Preview does not support multiple input sources

That’s a know issue tracked here: https://github.com/tobie/pr-preview/issues/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: https://github.com/tobie/pr-preview/issues/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 commented 3 years ago

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 https://github.com/tobie/pr-preview/issues/6#issuecomment-822252976 and https://github.com/tobie/pr-preview/issues/87

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

Filed https://github.com/w3c/spec-generator/issues/396

marcoscaceres commented 3 years ago

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

speced / speced-cg

Session idea: PR Preview #1