[Infrastructure] Previewing pull requests

[Dimitris Zacharopoulos (HARICA)]

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:
>
>  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)
>

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:
>
>  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
>

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.

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://cabforum.org/pipermail/infrastructure/attachments/20200512/d7029c1d/attachment.html>