Updating WAI Website Resources

Overview

The workflow described here enables parts of the WAI website to be developed independently through the lightweight GitHub Flow, and enables publication on the WAI website updates to be coordinated by the website manager.

One branch in each repository is designated as the “publication” branch. Publication branches are lightly protected so that all changes to the WAI website are merged only by the site manager, technical lead, or maintainers — currently Shawn.
Editors provide a single pull request to the publication branch when updates are ready for publication.
Scheduled updates are usually published/deployed on Tuesdays.

Workflow

Each Working Group and editorial team defines their own workflow for drafting, reviewing, approving, and submitting updates.
- Pull request used during development are made to the default branch or other branches, NOT the publication branch.
- Netlify previews are available for all pull requests.
- Editors and/or project managers ensure early coordination on user interface, shared component, and content updates, per below.
When the editor wants updates published, they:
- Create a single pull request to the “publication” branch. How to and details in Creating a pull request to the publication branch below.
  - Include a brief summary of the changes. Explain everything that the website manager and/or technical lead needs to particularly be aware of.
  - Include a link to the Task Force and/or Working Group approval to publish.
  - Include details on any shared components or other things that need updating outside this resource repo. For example, Liquid variables provided in the resource’s _config.yml file that need to be copied across to the wai-website repo.
  - Assign it to @shawna_slh.
- Add a link to the pull request in the Publication Schedule (requires W3C Member login)
  - If other than a simple content update, coordinate with Shawn at least the week before.
  - If a simple content update, then by Monday midnight US Eastern time.
When the updates are published, the publisher does an initial check that things worked, and adds a comment in the pull request so the editors can do additional checks.

Coordinating User Interface, Shared Component, and Content Updates

Editors are responsible for ensuring that everything submitted for publication is indeed ready to publish — that it is approved, tested, and carefully quality checked. Website publishers are not able to do thorough reviews before publication.

All user interface ideas must be coordinated with the WAI website manager (currently Shawn) — ideally from the start of the idea, before people get attached to a particular option.
All updates to shared components or other beyond the individual repo — to the website theme, config files, navigation.yml, etc. — must be coordinated with the WAI website technical lead before a pull request is submitted to the publication branch.
All content updates must be approved by the Working Group that owns the repo content. In some cases, the Working Group has provided blanket approval for some types of updates, such as for some aspects of ACT Rules.

Details

Publication branches are protected, and editable only by W3C staff. All updates to appear in the WAI website are on this branch and will be merged by the site manager, technical lead, or maintainers — currently Shawn. As backup, any W3C staff (as W3C organization administrators) can edit or merge into the publication branch. To enable this, resource editors and other non-W3C-team have maximum repository access privileges “write”.

Resource editors provide updates in a single pull request to the publication branch. If there are multiple updates, they can be provided in the default branch (usually main or master), with a single pull request for that branch to be merged into the publication branch.

Only highly-trusted individuals should have write access to the default branch. Before updates are made in the default branch, content updates have been approved by the Working Group, user interface updates approved by the website manager, and shared component updates approved by the technical lead.

WAI website updates are usually published/deployed on Tuesdays about 13:30UTC. Deploys on other days can be arranged ahead of time. Note that the site manager or maintainers will also likely deploy the site at other times, without prior notice.

Editors work with the WAI site manager and technical lead to coordinate on considerations for:

fit with existing content
editorial style
user experience
accessibility
internationalization
theme and coding
information architecture
technical integration

Site-Wide Components

WAI website components:

https://github.com/w3c/wai-website-theme/ - Jekyll theme - includes components and layouts as well as docs
https://wai-website-theme.netlify.app/components/ - descriptions of design components
https://github.com/w3c/wai-website-theme/blob/master/_layouts/standalone_resource.html - layout for new minimal resources - used for report tools, supplemental guidance, ACT Rules, ARIA APG
- as described in https://github.com/w3c/wai-minimal-header-design/

Currently, issues related to these components are in different places. We are in the process of moving all issues to: https://github.com/w3c/wai-website/issues/ so they are in one place. We will use labels to group them.

Please put any new issues in https://github.com/w3c/wai-website/issues/ — and feel free to move existing issues there, too.

Creating a pull request to the publication branch

From the Pull Request section, click the “New” button:

Change the base branch to “publication”. Click the “Create pull request” button.

For the title, put something like “For publication/deploy on Tuesday 9 September 2023”. (Please do not use a number for the month.)

In the comments,

Include a brief summary of the changes. Often a list of the PRs to the main branch since the last publication provides a good summary, and also helps us followup if we need more info.
Explain everything that the website manager and/or technical lead needs to particularly be aware of.

The purpose of this information is:

to confirm that anything that needs review from Shawn or other got that review
for the publisher to use for spot checking that the deploy worked
for troubleshooting if anything goes wrong