This is an unpublished draft preview that might include content that is not yet approved. The published website is at w3.org/WAI/.

Publication of the WAI Website

@@ {Publication info moved from “Technical Information” page. For Steve or others to edit (or delete if redundant with info later in the page – or, leave as a summary :-}:

Deployment

Deployment consist of publication to the main site via github pages. The W3C website uses a reverse proxy so the WAI site pages appear within it mounted at www.w3.org/WAI/ Publication is started by filling in the GitHub new release form which triggers the GitHub deploy Action to perform the build and deployment.

The build process consists of several steps for all repos:

  1. checkout git repo including submodules
  2. install all dependencies (ie Ruby Gems)
  3. use the Ruby bundle command to invoke Jekyll for the build
  4. deploy to github pages
  5. update urls for inclusion in www.w3.org/WAI/.

When a release is made in GitHub the GitHub deployaction builds and then generates a manifest.txt, copies the built static files to github pages rather than let GitHubPages run Jeckyl again and finally invokes https://www.w3.org/services/update-wai-map' to update the w3c URL mapping. Netlify build use the same first 3 steps.

The GitHub Action runs on ubuntu-latest (currently Focal 20.04) and Netlify uses Xenial (16.04).

GitHub pages are configured so the latest commit on the branch gh-pages is served via GitHub http access.

To deploy, in GitHub:

  1. in the wai-website repo select Releases on the right
  2. select draft a new release
  3. fill in the details and click publish release
  4. navigate to Actions and select Deploy
  5. click on the top line to view the log and watch progress

Rollback

I case of a deploy breaking the site it is possible to rollback to an earlier version. This works by deleting the latest checkins from the gh-pages branch. It does not touch the source or re-build.

In GitHub:

  1. in the wai-website repo code section select the gh-pages branch
  2. select the commits history view
  3. identify the commit you want to rollback to - usually the second from the top.
  4. click the ‘clipboard’ icon on the right of the row. this will copy the commit id to clipboard
  5. got to Actions in the top Navigation
  6. select Rollback Website
  7. click Run workflow button on the right
  8. in the first edit box paste the id you previously copied
  9. in the second edit box type yes and click Run Workflow

Refresh your browser to check the WAI website has rolled back. You may have a wait a minute or two for caching. @@

1. Generate Site Files –

TODO add Netlify previews

There are two ways to generate the site. 1.1 shows how to do it on GitHub, 1.2 shows how to render it on your local machine for testing.

1.1 is the method used to deploy the site, and 1.2 may be useful for experiments or debugging.

1.1 Generate and Publish Using GitHub Action

1.1.1 Create a Release on GitHub

Go to the Draft Release page. Enter today’s date into the “Tag Version” input field, in the format: YYYY-MMmmm-DD e.g, 2020-12Dec-25.

For multiple releases on one day, add a letter to the end: YYYY-MMmmm-DD-x with x replaced by a letter, starting with a.

Click the “Publish Release” button.

This process starts a GitHub Action which – at the time of writing – automatically performs the following steps:

  1. Check out repository
  2. Update external resources
  3. Commit the updated resources to the repository (if any)
  4. Builds the site into the _site folder
  5. Creates a list of generated resources in _site/manifest.txt
  6. Publishes the _site folder to the gh-pages branch
  7. Creates a zip archive of that folder
  8. Attaches that zip archive to the release
  9. Updates the URL mapping on the W3C site

You can follow the generation of the files in the Actions tab on GitHub. Once the generation is done (after about 6–9 minutes), reload the release (from the releases page) and you can find that a build.zip has been attached to the release:

Note: This build.zip file is not used anywhere and may no longer be needed, but kept for now in case it can help with debugging.

If each step of the GitHub Action has been successful, the newly-generated site should have been published to GitHub Pages and the URL mapping on www.w3.org updated to proxy requests for the URLs listed in manifest.txt to GitHub Pages instead of being served from W3C’s legacy document tree.

Implementation details: one, two (W3C staff-restricted)

1.1.2 Debugging If Something Goes Wrong

Visit the GitHub Actions page and click on the most recent run, then click build in the left side nav bar. That will show a log of the actions; each one is expandable and will show more details including any errors that came up.

If your expected resource is not available on www.w3.org, check that there is an entry for it in the manifest.txt file.

If there is no entry for the expected resource in the manifest.txt file, there may be an issue with the build process.

If there is an entry in manifest.txt but it is not available via www.w3.org, you can check the map file update tool to view info about the last update and the number of entries, and click the Update map file button to cause it to force a refresh of the map file on W3C’s site. This may be necessary if there was a timing issue between the GitHub Pages site being updated and the map file being updated on W3C’s site, for example if it took longer than usual for GitHub Pages to be updated.

1.2 Generate Site Locally for Testing

This method should normally not be necessary, but may be useful for those wanting to generate a local copy of the site for testing or experiments.

Note: The following steps were tested on a Unix, Max OS and Ubuntu on Windows Subsystem for Linux (WSL) 2. Problems with Ruby and the use of symlinks exclude using Windows native shells. In all cases you will need git and Ruby installed, on WSL dev-essentials was required to build modules.

1.2.1 Locally Clone & Set Up the Repository

The steps in this step 0

Clone the repository to your local computer to build. For example, the following command would clone the repository to your home folder:

git clone git@github.com:w3c/wai-website.git ~/wai-website

Then go to your checked out version of the site:

cd ~/wai-website

then install bundler:

gem install bundler

And install the dependencies. This step with bundler makes sure that everyone has the same versions of Jekyll & Plugins:

bundle install

(Yes, the application is called bundler, the command is bundle.)

Then, you also need to initialize the submodules:

git submodule init
git submodule update --remote

1.2.1 Update Submodules

Submodules are links to the individual resources. wai-website is our main repository and individual resources like wai-people-use-web are then linked to as submodules.

The main repository keeps the structure of the website and then pulls the content from the individual resources.

Please ensure that you have the current version of the repository downloaded. So in your clone of the repository (for example in ~/wai-website) run:

git pull

Then update the submodules:

git submodule update --remote && git add _external && git commit -m "Update Externals" && git push

This code does four things: It updates the submodules, adds them to a commit, locks that commit in and pushes it back to the server.

1.2.2 Build Site

Occasionally the bundler code is outdated or stops working, in that case run a bundle update in the repository folder.

Afterwards, build the site:

bundle exec jekyll build --config "_config.yml,_config_prod.yml" --incremental

This command takes a couple of minutes to run. It outputs certain warnings that can be ignored:

Invalid theme folder: _sass
WARNING: skipped symlink /private/var/folders/br/73fx4d5s7dbb0j18tqdt6hfh0000gn/T/jekyll-remote-theme-20190924-62884-9cxak3/_data/lang.json
WARNING: skipped symlink /private/var/folders/br/73fx4d5s7dbb0j18tqdt6hfh0000gn/T/jekyll-remote-theme-20190924-62884-9cxak3/_data/techniques.yml
WARNING: skipped symlink /private/var/folders/br/73fx4d5s7dbb0j18tqdt6hfh0000gn/T/jekyll-remote-theme-20190924-62884-9cxak3/_data/translations.yml
WARNING: skipped symlink /private/var/folders/br/73fx4d5s7dbb0j18tqdt6hfh0000gn/T/jekyll-remote-theme-20190924-62884-9cxak3/_data/wcag.yml

The generated site is then output in the _site sub directory, for example in ~/wai-website/_site/

Back to Top

This is an unpublished draft preview that might include content that is not yet approved. The published website is at w3.org/WAI/.