A guide to BAU reviews

In this guide we will cover best practices when reviewing a BAU (business as usual) pull request.

Copy

BAU requests, be they copy updates or page refreshes/new pages should have a copy doc attached to the request. These should be considered the source of truth for copy. For new pages, all of the copy on the doc should be checked while for existing pages the relevant changes will be in suggestion mode as in the example below. The quickest way to check the content is to ctrl+f a given section and cross-reference.

Design

Page refreshes and new pages will have a figma file attached to the PR. Designers are tasked with reviewing such PRs as well, but dev QA will also involve going through this file to ensure nothing has been missed. The page should also be checked against all screen sizes to ensure responsiveness.

Some additional things to look out for include spacing and image ratios if applicable. To see these, turn on dev mode and click on a component. Note that if the component you are reviewing is a jinja pattern it’s not necessary to check these as they are provided by Vanilla by default.

Vanilla

The vast majority of repos maintained by the Sites tribe are on Vanilla 4. It is important to remain up to date with latest best practices and components. Starting in V4.11 the Vanilla team introduced Jinja patterns which are plug-and-play marcos that have already gone through the design process. At time of writing there are 8 patterns* and these should be used instead of hard-coding the same component. This list will continue to expand so please make sure to review the newest additions on latest releases.

Some additional common components include:

Sections
Strips (typically used for CTA sections)
Logo clouds
CTA blocks
and the Grid (please note that legacy grid is still heavily used for now)

*The ubuntu.com and canonical.com codebases also include some custom Jinja patterns. These will eventually all be up-streamed to Vanilla but for now you can find each respective list under /templates/macros.

Sites tribe conventions and best practices

There are a few conventions maintained across all of our repos which should be maintained. These include:

Using the image template instead of the base asset link. You can find this by clicking on the “Dev tag” link version of the relevant asset on the asset manager. In order for this to be formatted correctly there should be no spacing between “image” and the opening parenthesis like so:
Formatting using djlint. We have a check for this on our repos, if this fails please flag it to the author.
HTML encoding should be used for spaces in link URLs, em and en dashes, and non-breaking spaces and right angle quotes (the combination most commonly used in CTA links, eg: <a href="/desktop/organizations">Read more about Ubuntu workstations &rsaquo;</a>).
CTA’s that are not styled as buttons should always have a trailing  &rsaquo; as in the example above.
All links are <a> tags, regardless of styling.
Above the fold images should be auto loaded and those below should be lazy loaded.
Use lite-youtube to lazy load YouTube videos as in the following example:

          <lite-youtube videoid="q5yM4ZYwB_s"
                  width="560"
                  height="315"
                  posterquality="maxresdefault"
                  videotitle="Ubuntu 24.04 LTS Noble Numbat | 20 years of Ubuntu"
                  class="u-embedded-media__element"
          >
            <a href="https://youtube.com/watch?v=q5yM4ZYwB_s" title="Play Video">
              <span class="lyt-visually-hidden">Ubuntu 24.04 LTS Noble Numbat | 20 years of Ubuntu</span>
            </a>
          </lite-youtube>

Logo alt text should be set as the name of the company and use appropriate capitalization, eg: ‘Google Cloud’.

Accessibility

A general rule of thumb for all of our sites is that all information this is available to users who do not need/use assistive technology should be equally accessible to users who do. Sometimes as a part of the review process this will involve an a11y review. In addition to reviewing the code this involves using your screen reader to ensure content is read out as expected. That said, not every page needs an a11y review and we will go over some examples where it is indeed needed. Lastly, care should be taken to make sure we’re not adding unnecessary noise for users. This means that rather than adding alt text to every image, it should only be added for images that convey some sort of information to the user. Decorative images should have a null alt attribute so that assistive technologies know to ignore it.

a11y review candidates:

Data visualization. Non-decorative graphs need descriptive alt text that conveys the entirety of the information it conveys to users using assistive tech. It is the requester’s responsibility to ensure this is provided to the author, but it should be checked for during pr review.
Repeated link copy. Sometimes link copy will be repeated throughout sections on a page. These should include additional context so that links are distinguishable for sreen readers. Example:
Accesible flags. Sometimes a design will convey information in a way that might be visually intuitive, but is less so for folks using assistive tech. As with repeated link copy, context should be added to link the necesary information to the relevant visual flag. In the following example we have an asterisk that is meant to convey information to the user. Since that is not inhenrently connected to the relevant text, the context is added for screen readers and hidden from the VP.

Tests and CI checks

Currently the only failing actions that we consider to be blockers are the ones set as required. This list may change in the future (eg at time of writing this guide the Percy check integration is not complete but will be set to required once ready) and will be communicated to the team as needed.

Last updated 9 days ago.

Help improve this document in the forum.