[Infrastructure] Experiment with Git publishing to cabforum.org

Tue Nov 30 20:11:03 UTC 2021

Thanks!

On Tue, Nov 30, 2021, 8:42 AM Jos Purvis (jopurvis) via Infrastructure <
infrastructure at cabforum.org> wrote:

> Using our test site, I set up the Git It Write plugin and then created a
> public repository with a few Markdown versions of minutes and ballots, then
> “published” them by pulling them into the test server. Have a look at the
> below info and let’s discuss at this week’s meeting.
>
>
>
> *TL;DR Version:* It works! And it works pretty well, too—the resulting
> pages look just like the posts we normally create by hand. Here’s a couple
> samples:
>
>    - https://tj4.9bc.myftpupload.com/2021/11/30/20210916-2/ (SCWG Minutes
>    from 2021-09-16)
>    - https://tj4.9bc.myftpupload.com/2021/11/30/sc48/ (Ballot SC48)
>
>
>
> Here’s the source repository:
>
>             https://github.com/castillar/proceedings-md
>
>
>
> *Longer Version:*
>
> The way GIW works is to pull Markdown files from a public Github repo and
> then convert them into static WordPress posts. You can either do the sync
> manually on demand or by using a webhook from Github that will poke the
> server when an update is pushed to the branch it’s watching. The advantage
> of this is that we get Git review/update/approve workflows for things like
> ballots and minutes that need a standard format and review process, without
> imposing that on the rest of the website.
>
>
>
> Couple things I noticed:
>
>    - GIW will watch specific branches, but it does need a public
>    repository. This would mean some extra steps for minutes, which require
>    private review prior to being made publicly viewable. I have some ideas for
>    this below, or we might decide that minutes are less important for this
>    process and just focus on this for ballots.
>    - The Git flow is particularly useful for ballots, as we could make
>    the Github repo the standard location for ballot proposals. Propose the
>    ballot as a pull request, update the ballot pull request as it passes
>    through discussion and voting, and then approve the pull request when
>    voting is complete to automatically create a ballot record. In addition, we
>    can code some Github workflows to accompany this, adding and modifying
>    boilerplate on the ballot record to indicate IPR and link the final ballot
>    to the updated document(s) through that process.
>    - The information flow is one-way only: if you edit a post on
>    WordPress after importing it, those changes are not propagated back to
>    Github. In addition, those changes may be overwritten the next time you run
>    an import, so anything we’re publishing through Github needs to be
>    exclusively edited in Github.
>    - GIW creates the post name from the filename, so if we have two files
>    named the same thing, it’s going to create them as 20210916 and 20210916-2
>    in WordPress. Filenames therefore need to be globally unique, which would
>    push for a more flat layout than I have (more like “ballots under this
>    directory with unique names, minutes under this directory with unique
>    names” rather than creating folders to organize content.
>
>
>
> For the minutes process, I can see two potential workarounds for the
> public repo problem:
>
>    1. Create a private repo for each working group (or one private repo
>    for all, if we’re OK with that) and do the initial review of the minutes on
>    that repo. This would require anyone wanting to view the minutes to have a
>    Github account added to the repo, or we could probably configure it to
>    publish a copy over email to the management list. Once the minutes are
>    approved in the private repo, they’d be fast-tracked through the public
>    repo into WordPress. That would obviate some of the advantage of the public
>    repo, but we could still use it for ballots and as a standard publishing
>    method (and to make sure the format is correct before publishing to the
>    website).
>    2. Continue to do the private review of the minutes on the management
>    mailer. When the minutes are approved by the relevant working group, they’d
>    submit a pull request to the public repo, and the public repo owners would
>    just make sure the formatting is correct and then approve it. This is the
>    simpler option, although it does remove some of the git advantages.
>
>
>
> In addition, there’s the question of publication dates and layout. The
> repo is laid out like this:
>
> proceedings-md/
>
> minutes/
>
> forum/
>
> datestamp.md # e.g., 20210916.md
>
> scwg/
>
> datestamp.md
>
> ballots/
>
> tag-ballotnum.md # # e.g., sc48.md or forum-13.md
>
> GIW then converts this into WordPress layout by creating a Post page for
> each MD file it finds in the repository. It first creates a post like this:
>
> https://tj4.9bc.myftpupload.com/2021/11/30/20210916/
>
> The URL comes from the date of import (that is, the date GIW pulled the
> post into WordPress) plus the name of the file. Folders within the imported
> layout don’t seem to be mapped to slugs on WordPress, so we should probably
> just push for a flat repo layout as noted above.
>
> The downside of this is that if we import all of this material into
> WordPress, it’s all going to appear as if everything was created on the
> same day. I haven’t played with it enough yet to know whether we can
> somehow set the creation date in the YAML front material on the post. I did
> check and we can manually edit the WordPress post to change the publication
> date, but the plugin will then create duplicate posts on the next import
> because it doesn’t see them as identical anymore, so that’s not going to be
> a good option. Going forward, things should be OK since the site will
> import new content close to the date of publication in Github, but for the
> initial import it might be problematic. One option would be to *not*
> import old content to Github, and simply start tracking new content from XX
> date forward, so that older content already on the website remains
> unchanged.
>
>
>
> --
> Jos Purvis (jopurvis at cisco.com)
> .:|:.:|:. cisco systems  | Cryptographic Services
> PGP: 0xFD802FEE07D19105  | Controls & Trust Verification
>
>
>
>
> _______________________________________________
> Infrastructure mailing list
> Infrastructure at cabforum.org
> https://lists.cabforum.org/mailman/listinfo/infrastructure
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.cabforum.org/pipermail/infrastructure/attachments/20211130/1edef1a3/attachment.html>