Using branch names instead of branched yaml files for building docs.fp.o?

[Ben Cotton]

Hi docs team,

mattdm recently suggested we should rename the default branch of
council-docs from "master" to something else[1]. I suggested "prod"
because I have ulterior motives.

Right now, we have separate branches for building the production and
staging docs.fp.o. This makes staging useful for testing changes to
the build system itself, but not for content. Granted, people can (and
should) test content changes locally before pushing, but for changes
that span across repos or for sharing rendered changes with someone
else for review, that becomes more challenging.

Would it be possible to configure things such that docs.stg.fp.o build
from the repos' 'stg' branches and the main docs sites build from the
'prod' branches? This way, every docs repo that gets included by
Antora can have stage and production content for "free". Then, for
example, if I made a big structural change to the Council docs, I
could do that on the stage branch so that it would be built and
visible to anyone I wanted to share it with, but the production
content would be untouched until we were ready to merge.

Would it be as simple as changing line 6 on site.yml to be 'prod' on
the prod branch and 'stg' on the stage branch? (Or better, could we
pull it from some environment variable/file/whatever?)

Assuming this is both technically possible and also desirable, would
it be possible to have the production docs site support both "master"
and "prod" as branch names to provide a migration window. Or would we
have to migrate to this model by updating the site.yml on a per-repo
basis?

[1] https://pagure.io/Fedora-Council/council-docs/issue/86
[2] https://pagure.io/fedora-docs/docs-fp-o/blob/prod/f/site.yml#_6

Le 21 août 2020 00:28:16 GMT+03:00, Ben Cotton  a écrit :
> Hi docs team,
>
> mattdm recently suggested we should rename the default branch of
> council-docs from "master" to something else[1]. I suggested "prod"
> because I have ulterior motives.
>
> Right now, we have separate branches for building the production and
> staging docs.fp.o. This makes staging useful for testing changes to
> the build system itself, but not for content. Granted, people can (and
> should) test content changes locally before pushing, but for changes
> that span across repos or for sharing rendered changes with someone
> else for review, that becomes more challenging.
>
> Would it be possible to configure things such that docs.stg.fp.o build
> from the repos' 'stg' branches and the main docs sites build from the
> 'prod' branches? This way, every docs repo that gets included by
> Antora can have stage and production content for "free". Then, for
> example, if I made a big structural change to the Council docs, I
> could do that on the stage branch so that it would be built and
> visible to anyone I wanted to share it with, but the production
> content would be untouched until we were ready to merge.
>
> Would it be as simple as changing line 6 on site.yml to be 'prod' on
> the prod branch and 'stg' on the stage branch? (Or better, could we
> pull it from some environment variable/file/whatever?)
>
> Assuming this is both technically possible and also desirable, would
> it be possible to have the production docs site support both "master"
> and "prod" as branch names to provide a migration window. Or would we
> have to migrate to this model by updating the site.yml on a per-repo
> basis?
>
> [1] https://pagure.io/Fedora-Council/council-docs/issue/86
> [2] https://pagure.io/fedora-docs/docs-fp-o/blob/prod/f/site.yml#_6

Hello, doing it is easy, "by updating the site.yml on a per-repo basis". The one on docs-fp-o

As far as I know, changing the default branch isn't possible.

For local testing, having two yaml files makes it easier for user to understand what they see.

In addition, this change have no impact on localization system.
--
Jean-Baptiste

[Justin W. Flory (he/him)]

Hey Ben,

Personally I am -1 to this approach with git branches because I think
this adds more work and complexity to existing Fedora Docs workflows in
other teams.

In theory it makes sense to have a staging and production version of
docs, but I don't see this being useful in practice (at least with the
docs repos I maintain). Most content contributions I see are minor,
small changes that do not warrant a staging deploy to test. I think
using git branches for this is confusing. For repos I maintain, if
`prod` was the default branch, I would likely choose not to make a
`staging` branch because I feel it is unnecessary.

We have invested a lot of time and effort in the container build scripts
for the docs, which is cross-platform and generally works well (if you
have updated versions of the scripts and not the initial versions circa
2017/2018). I think the emphasis on local testing is the right approach
for testing content changes. As a maintainer, if I was concerned about a
content change, I would pull it locally from a PR, build it myself, and
then decide what to do based on how renders locally.

I understand the motivation for this and it is a good idea, but I think
git branches are the wrong approach. The original idea that we had at
the 2018 Docs FAD was staging docs would be built instantly, maybe with
webhooks. This would allow someone to quickly see their changes in the
published Fedora Docs system. The "production" docs would continue to
built once an hour, like they are now. This approach makes the staging /
production separation more seamless and takes the responsibility off of
the person making a PR to decide what branch to make their PR to (if
they even realize there are other branches in the first place).

Curious for other thoughts on this.

- Justin

On 8/20/20 5:28 PM, Ben Cotton wrote:
> Hi docs team,
>
> mattdm recently suggested we should rename the default branch of
> council-docs from "master" to something else[1]. I suggested "prod"
> because I have ulterior motives.
>
> Right now, we have separate branches for building the production and
> staging docs.fp.o. This makes staging useful for testing changes to
> the build system itself, but not for content. Granted, people can (and
> should) test content changes locally before pushing, but for changes
> that span across repos or for sharing rendered changes with someone
> else for review, that becomes more challenging.
>
> Would it be possible to configure things such that docs.stg.fp.o build
> from the repos' 'stg' branches and the main docs sites build from the
> 'prod' branches? This way, every docs repo that gets included by
> Antora can have stage and production content for "free". Then, for
> example, if I made a big structural change to the Council docs, I
> could do that on the stage branch so that it would be built and
> visible to anyone I wanted to share it with, but the production
> content would be untouched until we were ready to merge.
>
> Would it be as simple as changing line 6 on site.yml to be 'prod' on
> the prod branch and 'stg' on the stage branch? (Or better, could we
> pull it from some environment variable/file/whatever?)
>
> Assuming this is both technically possible and also desirable, would
> it be possible to have the production docs site support both "master"
> and "prod" as branch names to provide a migration window. Or would we
> have to migrate to this model by updating the site.yml on a per-repo
> basis?
>
> [1] https://pagure.io/Fedora-Council/council-docs/issue/86
> [2] https://pagure.io/fedora-docs/docs-fp-o/blob/prod/f/site.yml#_6

[Ben Cotton]

On Mon, Aug 24, 2020 at 7:24 AM Justin W. Flory (he/him)
 wrote:
>

Replying out of order, because I can. :-)
> I understand the motivation for this and it is a good idea, but I think
> git branches are the wrong approach. The original idea that we had at
> the 2018 Docs FAD was staging docs would be built instantly, maybe with
> webhooks. This would allow someone to quickly see their changes in the
> published Fedora Docs system. The "production" docs would continue to
> built once an hour, like they are now. This approach makes the staging /
> production separation more seamless and takes the responsibility off of
> the person making a PR to decide what branch to make their PR to (if
> they even realize there are other branches in the first place).

That's solving a different problem, though. Or at least there's area
where they don't overlap. If I push at 1 minute before the hour and
the production build starts at the top of the hour, there's
essentially no staging. This is less about verifying the small changes
and more about getting review of major changes or changes that span
multiple repos.
> using git branches for this is confusing. For repos I maintain, if
> `prod` was the default branch, I would likely choose not to make a
> `staging` branch because I feel it is unnecessary.

And that's fine. The idea isn't to mandate a staging branch, but to
make having one trivial when it's desired. The intent, if everything
worked the way I would like (which I'm not entirely sure it does),
would be to have a staging branch be a zero-effort setup for those who
want it and entirely invisible to those who don't.

I recognize that this is a very rare use case, so I don't want to
spend much time debating it. You've convinced me that it's not worth
the trouble, so unless someone else thinks this is a brilliant idea
that we absolutely must do, I consider the matter settled. :-)