APG to WAI Build Pipeline Workflows Documentation

Overview

To support the content that exists in w3c/aria-practices to be available at on ARIA Authoring Practices Guide | APG | WAI | W3C, it has to be passed through transform functions present in this repository. These transforms are at /scripts/pre-build-library.

Then in coordination with the WAI team, it can be published as a live resource through their website. Additional details are available in the WAI Website Manual on preparing the w3c/wai-aria-practices repository for publication.

Pull Requests workflow

In order for a Pull Request submitted in w3c/aria-practices to be updated with a relevant link to support a proper review and provide an expectation of what the published content will be, workflows exist in both repositories to support that. The outline of that operation is as follows:

1. Contributor submits (or updates) a Pull Request branch on w3c/aria-practices. To provide context for future points, that branch will be APG_BRANCH_NAME.
2. w3c/aria-practices#wai-trigger-pr.yml is triggered, which then triggers w3c/wai-aria-practices#pr-create.yml. It does the following:
   1. If no branch exists on w3c/wai-aria-practices called apg/APG_BRANCH_NAME:
      1. The workflow creates an apg/APG_BRANCH_NAME branch.
      2. Pulls the latest updates from APG_BRANCH_NAME using .gitmodules.
      3. It then builds the project as specified in wai-aria-practices#README.md and commits the changes to the generated branch. This can be considered as "Site files update".
      4. Afterwards, it creates a draft Pull Request so a predictable Netlify URL is available (which can be considered as the "WAI-APG Preview Link" for the relevant APG_BRANCH_NAME change).
      5. That link is then used to update the top comment of the APG_BRANCH_NAME Pull Request which initially triggered the workflow and also provide a timestamp of when it was last built.
   2. If a branch exists on w3c/wai-aria-practices called apg/APG_BRANCH_NAME:
      1. Pulls the latest updates from APG_BRANCH using .gitmodules.
      2. It then builds the project as specified in wai-aria-practices#README.md and commits the changes to the generated branch. This can be considered as "Site files update".
      3. With a new commit being pushed, this will update the already created Pull Request.
      4. That link is then used to update the top comment of the APG_BRANCH_NAME Pull Request which initially triggered the workflow and also provide a timestamp of when it was last built.
3. If any of the above steps fail, the top comment of the APG_BRANCH_NAME Pull Request will instead be updated to state that the WAI-APG Preview Link failed to build, along with a link to the build failure log.

Generated branches and Pull Requests cleanup workflow

Given that several generated branches could exist on w3c/wai-aria-practices simply for the purpose of providing a preview link, it means therefore means there would be a need to clean up those branches once the review process has been completed so as to not unintentionally create and leave open, a multitude of draft PRs. The following describes what happens to ensure a branch and Pull Request clean up is done on this repository:

1. Contributor's Pull Request is merged or Contributor's Pull Request's branch is closed and the name of the branch is captured as APG_BRANCH_NAME.
2. w3c/aria-practices#wai-trigger-cleanup.yml is triggered, which then triggers w3c/wai-aria-practices#remove-branch.yml.
3. If a branch exists in w3c/wai-aria-practices called apg/APG_BRANCH_NAME then the branch is deleted, which in turn closes any open Pull Requests which were used for presenting a WAI-APG Preview Link.
4. If no branch is found, then the workflow will report that there is no additional action to take.

Deploy workflow

Whatever work is present on the main branch of this repository is what is considered as "ready for publication" in the context of a WAI Website deployment. That work is then used to create a "publication pull request" against the publication branch. Additional details are on that are described in the WAI Website Manual.

To keep the content on this repository's main in sync with the changes of the w3c/aria-practices main branch, the following is done:

1. A new commit is pushed to w3c/aria-practices main branch.
2. w3c/aria-practices#wai-trigger-deploy.yml is triggered, which then triggers w3c/wai-aria-practices#deploy.yml.
3. It then pulls the latest updates from w3c/aria-practices main branch through using .gitmodules.
4. It then builds the project as specified in wai-aria-practices#README.md and commits the changes to w3c/wai-aria-practices main branch.
5. This should then make the latest changes available at aria-practices.netlify.app in case it may be beneficial to view before any publication is made to ARIA Authoring Practices Guide | APG | WAI | W3C.