[Infrastructure] Previewing pull requests

Wed May 20 11:33:45 MST 2020

OK! As of last night, I got things working with Travis to the point that it successfully builds the new PDF/DOCX/HTML versions against castillar/cabforum-docs. So now I know what changes need making to the travis.yml, Makefile, and asset files to make everything happy.

Would it make sense to make a new branch specifically for those changes and then merge it after SC26, or to incorporate those changes into the existing pull request for SC26-pandoc-friendly that’s awaiting merging?

-- 
Jos Purvis (jopurvis at cisco.com)
.:|:.:|:. cisco systems | Cryptographic Services
PGP: 0xFD802FEE07D19105 | Controls and Trust Verification

From: Infrastructure <infrastructure-bounces at cabforum.org> on behalf of "Dimitris Zacharopoulos (HARICA)" <dzacharo at harica.gr>
Date: Tuesday, May 19, 2020 at 11:57 AM
To: Ryan Sleevi <sleevi at google.com>
Cc: "infrastructure at cabforum.org" <infrastructure at cabforum.org>
Subject: Re: [Infrastructure] Previewing pull requests

On 2020-05-12 5:52 μ.μ., Ryan Sleevi wrote:

On Tue, May 12, 2020 at 7:57 AM Dimitris Zacharopoulos (HARICA) <dzacharo at harica.gr> wrote:

Thanks Ryan for the detailed description and suggestions for moving forward. Please see below.

On 2020-05-07 9:48 μ.μ., Ryan Sleevi wrote:

On our last call, we talked a little about the workmode for previewing documents / edits. 

After talking around to a few of our other standards folks, it looks like the order I described is roughly correct.

That is, our "shovel ready" solution is to do so via "trusted" branches in the main cabforum/documents repository, which we've already got Travis set-up to automatically build and deploy artifacts from. They're "trusted" because anyone with a branch in cabforum/documents is implicitly trusted to just modify all the build system anyways :)

However, to have artifacts for pull requests, we need to split out the build/deploy steps. This is discussed a little at https://docs.travis-ci.com/user/pull-requests#pull-requests-and-security-restrictions . From looking around at other SDOs, the common approach seems to be setting up a web hook for inbound PRs, doing an isolated build of the artifacts, and then doing the deploy step from there.

The "isolated build" can be done a number of ways. The easiest way seems to be just to only fetch the .md files from arbitrary ("untrusted") pull requests and run those through the cabforum/document's build scripts, and then deploy those generated artifacts. If we want to change the build scripts / templates themselves, those would go through the trusted branches above.

Practically speaking, this means the order of operations is:

Jos sends a PR for the Makefile invocation to generate our artifacts
Jos and Ryan work through getting the dependencies right for both our dockerfile (for local editing) and the Travis bits (for the automated building)

This enables the following workflow:

Dimitris (or a chair/delegate, implicit throughout this remainder), when getting ready to merge a change, changes the base branch from being cabforum/documents:master into cabforum/documents:[something temporary Dimitris will use)
Dimitris squash&merges the pull request into that branch and apply the necessary corrections/edits
Travis is generating artifacts for every commit into this branch, which can be previewed for correctness
Dimitris creates a pull request from cabforum/documents:[something temporary] into cabforum/documents:[master]
Dimitris squash&merges into master (editing commit message as necessary)
Travis will again kick off new artifacts, this time for the commit to master
Dimitris deleges the cabforum/documents:[something temporary] branch, as it's no longer used
[Optional] Dimitris tags cabforum/documents:master @ that commit as being the appropriate document number (e.g. BR 1.6.7), creating multiple tags if multiple documents were updated (e.g. the same commit is tagged BR 1.9.1 and EVG 1.8.1, if both documents were updated)
This works for me and I assume the same applies to Wayne.

Longer term, the following steps would be necessary

Setup a webhook to fetch the .md files from a PR and run through the make/deploy setup
Wire the webhook to cabforum/master to fire when PRs are opened by anyone

And then the workflow just becomes:

Someone opens up a PR, enabling cabforum/documents maintainers to make edits
Voting happens
Dimitris makes edits directly into the PR's source branch
Previews are generated of those edits
Squash & Merged into cabforum/master
Documents published
[Optional] Tags created
How much additional effort do you think it would take to develop the second solution? If it's not feasible for the next couple of weeks, we can go with the first workflow and come back to it later.

More time than I have in the next few weeks :)

Thanks Ryan, you've already provided excellent guidance through this process. Let us know what we can do to take it one step closer to the finish line. Obviously we're all happy with the 8-step workflow :-)

Dimitris.

It would also help if we made some progress with cleaning up the official repo from the various old branches, as we agreed in Bratislava https://cabforum.org/pipermail/infrastructure/2020-February/000173.html

Thanks,
Dimitris.

_______________________________________________
Infrastructure mailing list
Infrastructure at cabforum.org
http://cabforum.org/mailman/listinfo/infrastructure

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://cabforum.org/pipermail/infrastructure/attachments/20200520/e7be446c/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 3699 bytes
Desc: not available
URL: <http://cabforum.org/pipermail/infrastructure/attachments/20200520/e7be446c/attachment-0001.p7s>