[Infrastructure] Previewing pull requests

[Ryan Sleevi]

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:

   1. Dimitris (or a chair/delegate, implicit throughout this remainder),
   when getting ready to merge a change, changes the base branch
   <https://github.blog/2016-08-15-change-the-base-branch-of-a-pull-request/>
   from being cabforum/documents:master into cabforum/documents:[something
   temporary Dimitris will use)
   2. Dimitris squash&merges the pull request into that branch and apply
   the necessary corrections/edits
   3. Travis is generating artifacts for every commit into this branch,
   which can be previewed for correctness
   4. Dimitris creates a pull request from cabforum/documents:[something
   temporary] into cabforum/documents:[master]
   5. Dimitris squash&merges into master (editing commit message as
   necessary)
   6. Travis will again kick off new artifacts, this time for the commit to
   master
   7. Dimitris deleges the cabforum/documents:[something temporary] branch,
   as it's no longer used
   8. [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)


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:

   1. Someone opens up a PR, enabling cabforum/documents maintainers to
   make edits
   2. Voting happens
   3. Dimitris makes edits directly into the PR's source branch
   4. Previews are generated of those edits
   5. Squash & Merged into cabforum/master
   6. Documents published
   7. [Optional] Tags created
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://cabforum.org/pipermail/infrastructure/attachments/20200507/088ede3c/attachment.html>