build: update build-docs website deployment to scheduled pipeline

[zhenmichael]

Moved website deployment step from build-docs to separate pipeline which triggers daily 8PM PST.

[tylerbutler]

Can we publish the site more frequently than once a day? I expect we will constantly get questions like, "i just made a docs change; when can I see it on ff.com?" I'd really like the answer to NOT be "wait ~24 hours and if it's not right, make another change and wait another 24 hours."

[zhenmichael]

Can we publish the site more frequently than once a day? I expect we will constantly get questions like, "i just made a docs change; when can I see it on ff.com?" I'd really like the answer to NOT be "wait ~24 hours and if it's not right, make another change and wait another 24 hours."

That makes sense, do you think every hour might be more appropriate for the schedule?

[Josmithr]

Can we publish the site more frequently than once a day? I expect we will constantly get questions like, "i just made a docs change; when can I see it on ff.com?" I'd really like the answer to NOT be "wait ~24 hours and if it's not right, make another change and wait another 24 hours."

Not arguing with having it run more frequently than every 24 hours, but note that devs can always do a manual run of the pipeline if they want to see their docs sooner. So every few hours might be a reasonable frequency?

[tylerbutler]

I understand that a scheduled run is simple, but is there no event-oriented design we could use here? Could every main branch commit that touches the docs folder result in a docs build, for example, in addition to the scheduled run? For comparison, the main-next job was run on a schedule, but it was also triggered by a next branch commit. That meant that in practice, the job would run immediately after the main/next PR was merged - because that created a commit in next.

[Josmithr]

I understand that a scheduled run is simple, but is there no event-oriented design we could use here? Could every main branch commit that touches the docs folder result in a docs build, for example, in addition to the scheduled run? For comparison, the main-next job was run on a schedule, but it was also triggered by a next branch commit. That meant that in practice, the job would run immediately after the main/next PR was merged - because that created a commit in next.

Yeah, triggering off of changes to docs still makes sense and sounds like a good idea. It won't catch changes to API documentation, but it will catch direct changes to website infra and our manually created documentation. And then we have the scheduled trigger (or on demand via ADO UI) to capture API docs changes.

[tylerbutler]

It won't catch changes to API documentation,

We could also trigger off of changes to the api-extractor generated reports.

[Josmithr]

Nit: for your PR title, I would probably use ci or build instead of docs, since this actually changes pipeline / deployment behaviors, and not just documentation changes.

[alexvy86]

A few small things below. I'm still concerned about the fact that the Azure function won't work though, because we haven't addressed the issue of versions.json not being present in docs/api.

[zhenmichael]

A few small things below. I'm still concerned about the fact that the Azure function won't work though, because we haven't addressed the issue of versions.json not being present in docs/api.

There were some recent changes to the docs/api/fallback/index.js such that it doesn't reference versions.json anymore. I merged the latest changes into this branch so I think there shouldn't be any referencing issues anymore. Currently, the build-docs pipeline publishes docs/api as a separate artifact.

[alexvy86]

Not sure I understand how the scheduled trigger covers release branches. It will run this pipeline from its version in main, that part I get, but the artifact that gets downloaded in that case will be from the single latest run of build - docs, regardless of what branch that is from, right?

[Josmithr]

Yeah, I think we should rephrase the comment here a bit. We should probably document 2 aspects here separately:

1. Capture the goals (publishing changes when API docs change on release branches and when docs changes on main)
2. Note the limitations and how our triggers attempt to satisfy our above goals.

[Josmithr]

And we should note that the 2.0 API docs are currently being published out of main, but will eventually come from our release branches. We have an ADO work item tracking that, right? We should probably reference that item in the notes here as well.

[Josmithr]

I left a few more comments. The main blocker I see currently is just ensuring that we perform all necessary build steps and compliance checks before we deploy the site. For that reason, I think we need to move some stages from build-docs to build-docs-website-deploy. I suspect build-docs probably just becomes build-api-docs (or something), which strictly generates and publishes the API docs artifacts.

[zhenmichael]

Updated the secure development steps to the build-docs-website-deploy pipeline.

Also, I ended up removing the scheduled pipeline since it seems to make more sense to trigger off of changes on main and release branches. For now, this pipeline will only trigger off of changes to main since we don't want to deploy documentation changes to old release branch versions. Once we have tracking for the latest release minor versions: https://dev.azure.com/fluidframework/internal/_workitems/edit/6739/, we can start triggering this pipeline on main as well as latest minor. Until then, I think it makes most sense to only trigger on main.

[Josmithr]

Since this pipeline is now effectively only about building and publishing API docs artifacts, we should update these docs to reflect that (and move any other docs to the other pipeline as appropriate).

We may also want to reconsider the pipeline/naming templates of these things. Since the other pipeline is the more general docs build one, it may want to be build-docs (so we can keep the existing pipeline definitions in ADO), and this may want to be build-api-docs-artifacts (or something), for which we'll need to define new pipelines in ADO.

[Josmithr]

I still think we need to run a build in this stage before we deploy, otherwise none of the Hugo output will exist, nor will things like markdown-magic run.

[Josmithr]

@zhenmichael Any status update on this? I just got a staleness notification for this PR. I think it's important we get this in before 2.0 GA.

[Josmithr]

@zhenmichael Do we have an alternative plan for this? We still have the issue where we are publishing v2 API docs from main, rather than the 2.x release branches, right?

[zhenmichael]

@zhenmichael Do we have an alternative plan for this? We still have the issue where we are publishing v2 API docs from main, rather than the 2.x release branches, right?

Yes, currently wrapping up this PR: #22252
It's a build-tools command which we can use to determine the latest minor release versions.

I realized this PR is probably overcomplicated for what we want to achieve. I'll create a follow-up PR after the build-tools changes is merged which involves:

• running a 'check release' stage before deployment step to determine if triggering branch matches a latest minor release
• using the result from 'check release' stage as a conditional check for running the deployment step