Build: use Bikeshed as source

[woutermont]

Alright, so I took the liberty of translating the existing working draft on the main branch to Bikeshed. To do a first comparison, I disabled some default options, which I think we should enable afterward; more on that later.

I invite you to compare the existing draft to the new rendered version.

Apart from the Bikeshed markdown and the rendered HTML, this PR also adds a GitHub workflow that renders the HTML from that Bikeshed file whenever a commit is pushed to a branch, to make sure the two are always in sync.

---

As I said, I turned off some default features of Bikeshed that we probably want to use:

• The auto-generated modern W3C sidebar with table of contents.
• The auto-generated "Conformance" section (the well-known piece of text explaining the meaning of conformance terms like MUST and SHOULD).
• The auto-generated index of definitions.

---

I did turn on Bikeshed's warning features, which showed that there are a number of problems with the current spec. We can solve these in separate issues/PRs:

• In a number of places, the current spec uses conformance terms in a non-normative section.
• The current spec defines a "Server", but never uses that term elsewhere.
• The current spec contains a number of broken links.
• The current spec refers to a number of obsolete specs.

---

Closes #35.

[webr3]

Cool, but struggling to square that with

Let's clarify something that seems to be causing some serious confusion: the draft of 2014 is the draft of 2014; we cannot go back in time and change that draft.

I do note however #41

Can you confirm if this is just a have a go type thing that stays as an open issue.

Or do you aim to fold this in to main and start making adjustments based on issues you've mentioned here, whilst side-lining the main work of the group in to a WIP/proposal branch?

Please clarify intent.

[woutermont]

Replied in https://github.com/w3c/WebID/issues/41#issuecomment-1894227305. TL;DR: the documents at /spec/ are the evolving working documents of this CG; the 2014-03-05 draft is the immutable version stored at /spec/drafts/ED-webid-20140305/.

Edit: corrected path.

[webr3]

I think it's great and commend your activity - however I'm in great confusion as to why you're iterating an old document, when the chair and group are working on a new, different, document?

[woutermont]

@webr, as far as I understood, the document @jacoscaz compiled based on converging consensus on different issues was meant only as a "guiding star", and each issue would still be iteratively added on top of the existing work.

[webr3]

Ack, I understood differently - that the new work would be taken as far as it could until consensus achieved, and then it would be discussed whether to publish in that form, or try to back port (if it fits) to the old spec.

[jacoscaz]

/chair hat on

To clarify, my document was indeed meant as a guiding star. In some scenarios it may have been used to bootstrap an actual new ED but if we all agree that we can simply consider the 2014 ED frozen into /spec/drafts/ED-webid-20140305/, then I think the best way forward would be to iterate as per https://github.com/w3c/WebID/issues/41#issuecomment-1894227305 . Doing so produces a better historical record, which is a point of concern amongst multiple members.

[webr3]

Momentum, audit trail, and iteration all need balanced here.

I'd point out that trying to iterate the current doc in to a new doc, where it's treated as the base, could be a very slow and difficult procedure.

Iterating your new document (Jacopo) will be a much faster process.

Perhaps iterate the new, then pull requests as and when to the original.

I worry very much that without a clean slate like working document, progress will be stale to non existent - hence why your new doc was needed at all.

Propose pause, focus on new doc, in manner discussed, then multiple pr back, if the old ed must be morphed in to the new whatever final doc(s) are.

[jacoscaz]

/chair hat off

@webr3 perhaps we could merge this in to have the transition to BikeShed represented atomically in the project's history, then have a "reset" commit that resets the document to a blank state, then add title, abstract and all the sections through different PRs? The 2014 ED will continue to live forever in /spec/drafts/ED-webid-20140305/ anyway, what we do with the working doc will not impact that.

[webr3]

/chair hat off

@webr3 perhaps we could merge this in to have the transition to BikeShed represented atomically in the project's history, then have a "reset" commit that resets the document to a blank state, then add title, abstract and all the sections through different PRs? The 2014 ED will continue to live forever in /spec/drafts/ED-webid-20230305/ anyway, what we do with the working doc will not impact that.

Honestly, as long as everyone is on same page and striding towards the same goal, then I'm happy.

A reset state sounds like a great idea - though it may be nicer to add the substance of the docs first, then abstract and title etc last?

Whatever gets us to that semi-clear end goal with the least effort and disagreement over pedantics or semantics wins for me :)

There's been more progress the last few days than the last few years, it's great.

[woutermont]

I'm still a proponent of gradually updating definitions and paragraphs, rather than throwing it all out. There's value in what is written there already. What we are changing is really not that much, and consists of relatively small atomic changes.

If everyone else thinks there is nothing to be gained that way, so be it. But if this is merely a practical matter of not knowing where or how to begin, I will gladly offer my help in starting a few PRs that integrate the consensus from @jacoscaz's draft as soon as this PR is merged.

[jacoscaz]

/chair hat off

@woutermont @webr3 there's clearly different sensibilities here. I myself stand somewhere in the middle, I can see the value of building upon the current document (as ported to BikeShed via this PR) and I can see the value of starting from scratch. I guess the best thing to do is to first try the more conservative way forward, building upon the current document. If that doesn't work due to excessive debate in how to change the current document we can try resetting to a blank slate.

[jacoscaz]

/chair hat on

as soon as this PR is merged

I'm going to wait a couple more days to give the group time to provide feedback on #46, #47, #48 and #49 and then will solicit feedback for this one.

[webr3]

If it's agreeable, my optimal would be both old doc to bikeshed new doc from scratch pull requests from new to old to sync as refined and "finalised" net result should be two documents with very little difference

I strongly feel the new needs to be unconstrained to take whatever shape is needed, probably multi-doc, that will not fit the old shape of docs.

[jacoscaz]

/chair hat on

Tagging some people to make sure this is on their radar: @namedgraph @acoburn @kidehen @jonassmedegaard @TallTed @melvincarvalho .

[kidehen]

All good.

[jacoscaz]

/chair hat on

Given that this PR is roughly a week old already and does not introduce any functional change to the draft it feels appropriate to set the deadline for review to 2024-01-29, in a week from now. For more information about deadlines for review, see our process in CONTRIBUTING.md .

[jacoscaz]

@woutermont may I ask you to please rebase this upon main and expand the README.md file with build instructions? I think the safest way to setup bikeshed is to install it via pip and invoke it via python3 -m as not everyone has their $PATH setup correctly for pip modules:

python3 -m pip install --upgrade bikeshed
python3 -m bikeshed spec spec/identity/index.bs

[TallTed]

Is there a PR-Preview-like thing, such that we can see the (mostly accurate) effect of each PR, including a DIFF rendition, before the PR is merged to the main branch?

(Or is that what you meant by "GitHub workflow that renders the HTML from that Bikeshed file whenever a commit is pushed to a branch"?)

[TallTed]

I have little doubt that BikeShed can be produced that will output HTML comparable if not identical to what ReSpec outputs. My concern about the switch is my minimal literacy in BikeShed versus my hard-won and still-imperfect literacy in ReSpec.

Can you please provide links to the ReSpec and BikeShed source files that render into old and new, respectively?

[TallTed]

[@jacoscaz] the safest way to setup bikeshed is to install it via pip and invoke it via python3 -m as not everyone has their $PATH setup correctly for pip modules

The above concerns me, as it sounds like one must work with a local git, python, bikeshed, pip, etc., environment ... and I work almost exclusively through GitHub's web interface.

This has not been an issue for my activity with ReSpec-based documents ... which is another contributor to my concern about the ReSpec→BikeShed change.

[woutermont]

@jacoscaz: do you prefer the README.md for the practical info regarding Bikeshed, or should I put it in CONTRIBUTING.md?

[woutermont]

@TallTed, thanks for the comments!

Is there a PR-Preview-like thing, such that we can see the (mostly accurate) effect of each PR, including a DIFF rendition, before the PR is merged to the main branch? [...] (Or is that what you meant by "GitHub workflow that renders the HTML from that Bikeshed file whenever a commit is pushed to a branch"?)

The way I currently set it up, GitHub runs a workflow on each push, that runs the Bikeshed processor (on spec/identity/index.bs) and checks if the result differs from the HTML already present in the repo (spec/identity/index.html); if so, it adds a commit that updates that HTML to reflect the latest changes. This way, every PR can easily include HTML Preview and HTML Diff links.

I have little doubt that BikeShed can be produced that will output HTML comparable if not identical to what ReSpec outputs. My concern about the switch is my minimal literacy in BikeShed versus my hard-won and still-imperfect literacy in ReSpec.

I can only speak for myself, of course, but I found the learning curve of Bikeshed a lot less steep than the one of ReSpec. If you or the group would like it, I can also summarize the basics in a 5min guide.

Can you please provide links to the ReSpec and BikeShed source files that render into old and new, respectively?

For the BikeShed source, that's easy: it is the spec/identity/index.bs file added in this PR. The ReSpec source, however, is not so clear. This repo does not actually contain the ReSpec source file, so I based the BikeShed source on the processed HTML (spec/identity/index.html on main), which includes the minor revisions since 2014. The only ReSpec source file I could find inside of this repo is the draft of 2011-11-23. Outside of the repo I could find the ReSpec source file on the old Mercurial repo (view-source), but I want to treat it with caution since it claims to be both the Editor's Draft of 2013-02-06 ('This Version' parameter) and the one of 2014-05-28 (subtitle).

[The setup described by @jacoscaz] concerns me, as it sounds like one must work with a local git, python, bikeshed, pip, etc., environment ... and I work almost exclusively through GitHub's web interface. [...] This has not been an issue for my activity with ReSpec-based documents ... which is another contributor to my concern about the ReSpec→BikeShed change.

No reason for concern. As described above, the GitHub workflow would take care of rendering the HTML from Bikeshed for you on every change. Moreover, local processing can also be achieved with a simple CURL call, and online processing is even simpler with the Bikeshed web form: simply paste / upload / reference a Bikeshed file, and it will render the HTML in a frame and give you any warnings/errors it might raise. Give it a try by pointing it to the raw Bikeshed file of this PR.

[jacoscaz]

/chair hat off

I can only speak for myself, of course, but I found the learning curve of Bikeshed a lot less steep than the one of ReSpec. If you or the group would like it, I can also summarize the basics in a 5min guide.

Same here. I'm relatively new to both and IMHO BikeShed is definitely friendlier to newcomers.

/chair hat on

@jacoscaz: do you prefer the README.md for the practical info regarding Bikeshed, or should I put it in CONTRIBUTING.md?

@woutermont I don't have much of a preference as to where to put the practical info - even a BUILD.md file can work for me. I'd be ok with whichever feels most appropriate to you. What I'm mostly worried about is to have the build process clearly documented and readily reproducible on one's local machine rather than having to figure it out by reading the files in .github. Not that we're talking about a complicated process, it took me 15 seconds before I even had a look at BikeShed's documentation; it's more the principle of it than anything else.

[termontwouter]

@jacoscaz, added a short intro guide. @TallTed, very interested in your opinion!

[TallTed]

@woutermont — You said (and @jacoscaz echoed, and again, and then @webr3 likewise) --

the 2014-03-05 draft is the immutable version stored at /spec/drafts/ED-webid-20230305/

By which I'm pretty sure you meant the full URI, https://github.com/w3c/WebID/tree/main/spec/drafts/ED-webid-20230305

But that leads to a 404. I think you meant 20230305 to be 20140305, i.e., WebID/tree/main/spec/drafts/ED-webid-20140305?

(Such errors persist, and replicate, and replicate, ad infinitum, and get harder and harder to fix — or even to figure out what was originally meant — with every echo. This is part of why I'm such a stickler for details.)

[jacoscaz]

/chair hat on

@woutermont Woah. That's well above and beyond what I had in mind. Super nice, thanks!

[jacoscaz]

/chair hat on

Thanks @TallTed for catching that, I'll be more careful in the future. See also #53 for similar issues.

[woutermont]

@TallTed, good catch. Corrected my original comment.

[jacoscaz]

/chair hat on

Today is the deadline for review of this PR. No objections have come in, @TallTed 's concerns have been resolved (judging by the +1s) and multiple participants have explicitly indicated their support for this. Good day to merge! Thanks @woutermont for taking this on.

[jacoscaz]

/chair hat on

@woutermont the automated build process via GH actions adds to the commit history even when committing changes that do not affect .bs files:

I think this is happening because https://github.com/w3c/WebID/blob/1294dbc49662b13268dc04f2b9acbcb44ecd3d66/.github/workflows/bikeshed.yml#L40 is being bypassed by the fact that the date in the built document is automatically updated to the date in which the build happens, thus making it different even though no actual change was made.

Do you think we could set the date manually?

[woutermont]

Aha, that's too bad... We could set the date manually, but that defeats the purpose of the workflow: if we can remember to change the date on each edit, we can just as well remember to run the processor, no?

I'll let this simmer a bit and see if I can come up with a better solution by tomorrow.

[jacoscaz]

/chair hat off

if we can remember to change the date on each edit, we can just as well remember to run the processor, no?

@woutermont not necessarily, IMHO. There's still convenience in having the flow run via GitHub actions so that git is the only tool required in order to work in this repo (see @TallTed 's concerns). In an unrelated project where we experienced a similar problem we settled on having a build-trigger file with a number to be incremented every time we need the build process to run.