Meeting minutes
Presentation
Video recording of this presentation and slides are available.
[Slide 1]
Denis: main goal is help maintain /TR up-to-date
… it should represent what the Web should be
[Slide 2]
Denis: in the past, the only way was to submit a request to the webmaster
… outside of moratorium, etc.
… this created delays, back-n-forth, etc.
… given how heavy the Process, the specs were not published often, resulting in an outdated /TR
… so we came with an automatic system
… it checks if the resources can be downloaded
[Slide 3]
Denis: now the system has limitations, such as can't be used for FPWD
… for CRs, limitation like if the doc changed WG
… Echidna can't handle shortname changes, some backward moves
[Slide 4]
Denis: you need your spec on GH. A group decision to use echidna.
… need a token for each spec, generated by team contact/chair
… should be kept private
… you'll need admin rights to your GH repo
[Slide 5]
Denis: for CR snapshots, you'll need Director and Comm approval
… w3c/transitions is used to get Director's approval
… the template to raise a transition can be found in the README
… when echidna will receive a request to publish
… it will check the requirements
<xfq> w3c/transitions/issues/199
<xfq> w3c/transitions/issues/261
Denis: see examples linked from the slides
[Slide 6]
Denis: introduced how to setup the repo
… Sid Vishnoi set up a GH action spec-prod to help
… spec-prod can generate snapshots from respec/bikesheds
<xfq> w3c/spec-prod/
Denis: run checks like borken links
… if the document is a compound one (like images, css, scripts), spec-prod will take care of them
[Slide 7]
Denis: first is to add the generated token
… added as a repo secret
… can be done in the settings of your repo
<xfq> https://github.com/w3c/{REPO_NAME}/settings/secrets/actions
[Slide 8]
Denis: [shows screenshot of adding a token]
[Slide 9]
Denis: you're now ready to create the GH action workflow
… it's a simple YAML file
… [shows example]
… here, the workflow runs on any pull requests and push on the main branch
… with this workflow, spec-prod will generate snapshots of the source doc (index.html or index.bs by default)
… if it's a push on the main, it will trigger echidna
[Slide 10]
Denis: parameters to customize the workflow
… (going through the list of parameters)
… if you want to receive an email after Echidna is done, use W3C_NOTIFICATIONS_CC
<xfq> w3c/spec-prod/blob/main/docs/options.md
[Slide 11]
Denis: using those variables in YAML example
[Slide 12]
Denis: mainly focusing on /TR but spec-prod can be used for GH pages
[Slide 13]
Denis: checking the results from Echidna
… the action tab will show you those
[Slide 14]
Denis: the screenshot sends a request to Echidna via a curl command
… and then query for results
… until the process returns for a result (public-tr-notifications@w3.org mailing list)
[Slide 15]
Denis: gives an overview on what is done and different steps
… for a CR Snapshot, you'll need a transition request
… [going through the workflow]
[Slide 16]
Denis: we presented spec-prod, which was built a few months ago
… it's the easiest to get started
… for alternatives, check the wiki
[Slide 17]
Denis: if issues arise, get help
[Slide 18]
Denis: for the future, want to remove more limitations
… some are related to the old process document
… also look at facilitating revising W3C Recommendations
… new things will get announced to spec-prod@w3.org
[end of video recording of this presentation]
<weiler> Denis, that was a great presentation. Thank you very much!
Q&A
Different workflows
Florian: thank for Echidna. My workflow is different. we don't publish on every commit in CSS
<dom> [you could have a different branch where you only push WG-agreed changes and use spec-prod for pushes on that branch]
Florian: substantive changes need to be explicitely approved for each publication
Florian: so the editor's draft hasn't been approved yet
… so we use Echidna in a manual way
… is there some intermediate way we could use?
… like flagging some drafts for publications but not others
Dom: simplest way would be a dedicated branch and you push on that branch. spec-prod would react only to that branch
Denis: an other event to listen is the one triggering the run manual
Francois: workflow_dispatch works perfectly for that indeed
<dom> [documenting workflow_dispatch as an example in spec-prod sounds like a good addition indeed]
<sidvishnoi> It's on roadmap: w3c/spec-prod#6
Mike: sounds like an issue for spec-prod. other groups might have the same process than the CSS WG Process.
... so would benefit from builtin support
Multiple publications of a document per day
Mike: what about the case when somebody pushes more than once a day
… I found that Echidna cannot republish to the same URL in /TR in multiple times on the same day
… echidna checks for the same URL
… and intentionally fails
Denis: Echidna should be able to publish multiple times on the same day. sounds like a bug
… please report it
<dom> [it may be a bug in spec-prod too. I recall spec-prod has special handling for this]
Florian: the new one will replace the old one
Denis: indeed, the previous version should be the one published one or more days before
Mike: that's the bug I'm running into
<dom> [there may be something about change of status shortnames (CR vs CRD vs WD)]
Denis: sounds like a spec-prod
Mike: but pubrules check those URLs
Florian: spec-prod fails to check if it's a same day publication
Mike: but those links are generated from biblio
Dom: might a mis-configuration between bikeshed/spec-prod
Denis: I'll follow up on this
<tidoust> [Relevant entry in Bikeshed doc: "Previous Version: from biblio" ]
Mike: we shouldn't have to manually set the previous version
<dom> [you don't have to do that]
Denis: agreed
<dom> ISSUE: get W3C build config from previously published TR doc
Denis: regarding different working group needs, I discussed with Sid about some WGs having different documents
Denis: I believe Sid is monitoring the issue
… so that's in the plan
<sidvishnoi> In progress: PR: Multiple input sources
Florian: that would be nice indeed
<dom> [btw, SO MANY THANKS TO SID!!!]
Linkchecker
Francois: the linkchecker has been disabled in spec-prod
… it's useful but prone to find false/positive
Sid: yes, it was generating too many false positive. looking into fixing some other issues next week as well
Sid: it should work for a publication
<denis> https://www.npmjs.com/package/href-checker
Denis: the linkchecker is in GH
plh: why 2 linkcheckers?
Denis: the new one will check javascript links
<dom> I maintain the linkchecker on an irregular basis w3c/link-checker/
Denis: Echidna doesn't check the links
… I'm thinking about further integration of the new linkchecker
Mike: Thank you Sid
<dom> +1
<denis> +1
<wseltzer> +1
<tidoust> +1
<xfq_> +1
<xiaoqian> +1
Mike: this has been a massive timesaver for /TR and github.io URLs
<wseltzer> MikeSmith++
<dom> sidvishnoi++
<wseltzer> sidvishnoi++
Denis: thank you Sid
<plh> I'm looking forward to deploy spec-prod for pointerevents
Markdown files
<Zakim> tidoust, you wanted to wonder about additional files during publication to gh-pages
Francois: one clarification: publication in GH pages/branches
… if there is a markdown document along, should I worry about them or will they get published?
Sid: sped-prod is only for specifications, so unless it's embedded, it won't. Can look into it
Francois: ok, this means I need to manually add them to the action
… the good thing with using GH pages, you end up with links not using the name of the branch
… and GH translates from markdown to HTML for you
Sid: I'll add an option: ISSUE: gh-pages: deploy additional files
Transitions
Florian: for transitions to CR or FPWD, can we redirect to a form to file the transition?
<dom> [anchoring the transition request flow into the publication request flow rather than the other way around]
Denis: we'd thinking about improving the echidna report
… since it's not always easy to understand it
… we can point folks to the right direction