Continue building future docs while current docs are frozen prior to a release

[dedemorton]

Prior to a release going out, we stop the automated builds. This causes problems when the release date slips because we continue to merge potentially build breaking changes. When we resume the builds, it sometimes takes us awhile to unwind and fix all the errors. Some asciidoc errors are very difficult to diagnose.

We need a way to continue building the docs for the next release while we freeze the builds for the current release.

@lcawl Proposed having a conf.yaml.next file so we can continue to run the doc builds without affecting the "frozen" docs.

[lcawl]

Yes, ideally the conf.yaml.next could be used to test upcoming changes (such as new branches or changes to "current") without affecting the current automatic builds.

It might be as simple as adding a --next parameter to the build_docs.pl --all command, which uses conf.yaml.next instead of conf.yaml

[nik9000]

We could probably build the docs without committing them. It'd get slower and slower as more and more books changed that we haven't committed, but it'd work.

I'm not 100% clear on why we want to pause the automated builds before a release. Pausing stops us from having to force push the built docs but that isn't super important. If the goal is to be able to keep building the docs even if there are errors I think it might be more useful to "pin" the hash that we use for a particular branch - basically ignoring the branch information in the repo and using our own.

[dedemorton]

@nik9000 The automated builds only build the stuff that's changed. A full build is required to update all of the labels and version drop-down lists, so we do this right before a release and force push.

In the past, we've had some problems with developers committing late changes that broke the build and had to be sorted out before we could get a clean, full build of the docs. This has resulted in releases being delayed by many hours. So we've started suspending the builds to get a clean build of the docs for the release rollout.

I'm all for any approach that allows us to continue building the docs but also get a full, clean build for release day.

[nik9000]

I get how we need a full rebuild and how folks can break things on release day. I really get it. I've broken them more than once, I'm sure. I'm just not sure how stopping the docs builds makes it better.

[dedemorton]

I think we pause the builds because we need to update the conf.yaml to bump versions and do not want to expose the version changes until after the release date.

[nik9000]

That makes sense.

[lcawl]

Right, it's a way of getting the time to generate a clean set of output (with the new "current" info, release-states, etc) that we can push very quickly on release day, then go back to automatic builds (and breakages) after the deadline. Otherwise we were delaying the release announcements as our docs were taking hours to rebuild everything with the new drop-downs.

I'm wondering instead of using a conf.yaml.next, we could just use the staging branch. I've never used it for anything other than previewing output, so I don't know how well it's kept in synch with master. For example, would it be feasible to do the release.next changes in staging and get a clean set of output say the day before the release, then cherry-pick those changes to master and move the good output html to master on release day? We'd lose any HTML changes in master between when we generated the "good" html and when we forced that push, however, so we might still end up having to do another full refresh, but at least we'd not be a bottleneck on everyone else.

[nik9000]

I think the simplest thing might be to stop deploying the master branch but keep updating it. I think I can turn that off by hand pretty easily.

…

On Thu, Jan 24, 2019, 19:45 Lisa Cawley ***@***.*** wrote: Right, it's a way of getting the time to generate a clean set of output (with the new "current" info, release-states, etc) that we can push very quickly on release day, then go back to automatic builds (and breakages) after the deadline. Otherwise we were delaying the release announcements as our docs were taking hours to rebuild *everything* with the new drop-downs. I'm wondering instead of using a conf.yaml.next, we could just use the staging branch. I've never used it for anything other than previewing output, so I don't know how well it's kept in synch with master. For example, would it be feasible to do the release.next changes in staging and got a clean set of output say the day before the release, then cherry-pick those changes to master and move the good output html to master on release day? We'd lose any HTML changes in master between when we generated the "good" html and when we forced that push, however, so we might still end up having to do another full refresh, but at least we'd not be a bottleneck on everyone else. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#559 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AANLomeyFbTjXt8zF1axqXis4s5ruxQTks5vGlOhgaJpZM4aR4Dr> .

[dedemorton]

I think this is no longer a problem because the build breaks less frequently now...so I am closing this puppy. 🐶