Task: Work with the community to determine any rules or requirements for who can run this workflow.

[oraNod]

Add to DaWGs meeting agenda to discuss any rules or requirements for running the workflow to build package docs. The outcome of this discussion, or result of any vote, will influence the overall publishing process.

For example, if the workflow pushes generated HTML that gets deployed to ReadTheDocs then suitable protection needs to be in place to prevent malicious or inappropriate content being published to docs.ansible.com. At the same time it would be beneficial to use the workflow for testing and development purposes, which might require less restrictive access.

[oraNod]

Meeting minutes

Discussed in the DaWGs meeting, April 23. Logs: https://forum.ansible.com/t/meeting-log-ansible-docs-2024-04-23-1554/5094

Question in the agenda

Does anyone have thoughts or opinions on who is allowed to run the workflow? At the moment, anyone who is a collaborator with write permissions can trigger the workflow.

It will be possible to do on-demand builds and the workflow will likely change to push generated HTML and assets to another repo so that ReadTheDocs builders are automatically triggered. With this in mind then suitable protection needs to be in place to prevent malicious or inappropriate content being deployed to docs.ansible.com. At the same time it would be beneficial to use the workflow for testing and development purposes, which might necessitate less restrictive access.

We could have two workflows, one for dev and one for prod. And perhaps we could protect the prod workflow with something like this workflow permission · Actions · GitHub Marketplace · GitHub

So what do people think? Is it necessary to have separate dev / prod workflows? Are there other options or techniques for limiting access to workflow_dispatch?

Summary

Confirmation steps

Q: do we have documentation with confirmation steps? like, if i did ever run that, how would I know if it failed? what should I check to reassure myself that it worked?

A: The workflow includes a step named "Build the Ansible community package docs". At the end of this step it shows the result of the make webdocs command that is used to generate the HTML and other assets.

When the build is successful, the output displays a message such as: build succeeded, 276 warnings. When the build fails, the output displays a failed message.

Potential improvement: Add an extra step or check that makes it easier to identify failures.

Identify person who ran the workflow

Q: does the workflow show who ran it? I know the docs show the date of the last update, is there some way to see more precisely when it ran and who kicked it off?

A: The workflow uses a workflow_dispatch trigger and shows the GitHub username of the person who ran the workflow, for example:

Identify the revision of the build

Q: maybe the last updated message and the workflow could include the commit from GitHub?

A: The workflow includes a step named "Checkout Ansible documentation" that includes the repository and branch of the build as well as the latest commit hash, for example:

Fetching the repository
  /usr/bin/git -c protocol.version=2 fetch --no-tags --prune --no-recurse-submodules --depth=1 origin +refs/heads/devel*:refs/remotes/origin/devel* +refs/tags/devel*:refs/tags/devel*
  From https://github.com/ansible/ansible-documentation
   * [new branch]      devel      -> origin/devel

Determining the checkout info
  /usr/bin/git branch --list --remote origin/devel
    origin/devel
/usr/bin/git sparse-checkout disable

Checking out the ref
  /usr/bin/git checkout --progress --force -B devel refs/remotes/origin/devel
  Switched to a new branch 'devel'
  branch 'devel' set up to track 'origin/devel'.
/usr/bin/git log -1 --format='%H'
'f2c60083362e9c6c767577129f73086d2b35416e'

In this example, the latest commit used in the build is this one: https://github.com/ansible/ansible-documentation/commit/f2c60083362e9c6c767577129f73086d2b35416e

Potential improvement: Add some logic to show the changeset between builds more clearly. This could be part of the deploy side.

Restricting access to builds

At the moment anyone who is a contributor with write access or above to the repository can trigger the workflow. General consensus from the DaWGs meeting seems to be to keep permissions limited.

For the question around two workflows, one for dev and one for prod, the discussion leaned towards having just one workflow.

[oraNod]

After some additional discussion, it seems like the preference is to restrict access to the workflow to members of the community-docs-maintainers group.

[oraNod]

Gathered some more details from the DaWGs meeting. Minutes available at: https://forum.ansible.com/t/meeting-log-ansible-docs-2024-04-30-1535/5222

Q1: I propose that we create a new target repo that the workflow pushes into in the ansible-community org. Does anyone think that sounds like a good or bad idea?

Q2: I also propose that we use the ansible alias in ReadTheDocs so that we end up with ansible.readthedocs.io/projects/ansible to match the current url context docs.ansible.com/ansible. Any considerations there or better ideas?

Q3: As a future effort, after we get things set up on RTD, propose that we add a workflow step that pushes to a gh-pages branch in the new repo that we’ll use to replace docs.testing.ansible.com. This keeps prod on RTD and test on GH pages. Does that sound reasonable?

general agreement on Q1 and Q2 (using ansible-community to host new artifact repo and projects/ansible for the RTD structure

A3 sure let's use github pages for our replacement test/staging site, blocked from google so it won't compete with the real thing

Q4: Do we want to add the package docs build as a PR check? That would give us more coverage than the docs-build which just covers core docs but would take >30 mins to run.

AGREED: keep full package docs build as a separate workflow not part of CI tests, but extend current CI tests to include all RST files to broaden scope of testing