Bills Blog Pre-Release Checklist

Things about the release candidate to validate before starting the steps in Bill’s Blog Release Process

Conventions

<Feat/Bug/Post-Branch> is the name of the branch that is being evaluated for release. The branch being evaluated for release will be referred to as the Release Candidate in this document.

Criteria and Evaluation

This document is a work in progress. In this first edition, many items are simply placeholders, indicated by “ToDo:”. This is especially true for areas that eventually will get automation to confirm the site conforms. For now, the checks should be done manually.

1. Checkout the <Feat/Bug/Post-Branch> with Visual Studio Code (VSC).
2. Review any warnings that appear in VSC’s problems pane. These are generated by various VSC linting, spell-checking and static analysis extensions. Clean up the underlying issue, or decide they are OK to live with for this release. Commit any changes made during this step to <Feat/Bug/Post-Branch> using a WIP commit message.

Check text spelling, grammar, and case-consistency on proper names

Using VSC for spell-checking

Use a spell checker plugin and ensure it reports no misspellings. I like the VSC extension Code Spell Checker

Using VSC for grammar checking

Use a grammar checker to ensure the writing meets basic grammar rules and if possible use it to simplify the writing style.

• [ToDo: write instructions on using the unofficial Grammarly VSC plugin on posts]

Ensure that proper names that refer to software or hardware concepts and company names, are consistent in their case across the site.

• [ToDo: write a script that tests the site for proper noun casing consistency]

Check post and page layout consistency

Posts should have a style consistent across all post categories, and pages should have a consistent style across the site. Both posts and pages should share common stylistic measures.

• [ToDo: (far future) write scripts that initialize new pages and posts with common styling, and write scripts that can read existing pages and posts and produce reports where styling does not follow the site guidelines]

• [ToDo: write a style guide for the pages and posts]

Site Checks

Site checks are tests to be performed against the total site. The following subsections provide details about classes of items to validate.

Here are some links to articles that discuss automating these checks, for future site releases

• End-to-end testing with GitLab CI/CD and WebdriverIO
• selenium
• Most Complete Selenium WebDriver C# Cheat Sheet
• Getting Started with WebDriver C# in 10 Minutes
• WebDriverManager.Net
• BrowserStack: App & Browser Testing Made Easy
• Nice tests to run in CI before deploying any website
  • HTML5 Validator - Markup validation
  • Detecting browser console error messages - use Selenium web driver, navigates to each page and calls driver.get_log(“browser”), asserts that there is no log.

Check Images and Videos

For posts and pages that include links to images both still and video, ensure the links properly reference images and videos hosted in the selected 3rd party clouds. Most of the images and videos for this site use Dropbox as the cloud hosting provider.

Ensure or check the following:

• Images and videos are created in multiple responsive sizes
• Image and video thumbnails are created
• Images and videos are checked for any PPI in the metadata,and scrubbed
• Images and videos comply with accessibility guidelines - Alt text and navigation aides
• Variable rate videos (some .mov files) have been converted to fixed-rate format. This helps prevent stuttering.
• Ensure that videos have been created in multiple resolutions for different sized devices

• Ensure the correctness of the final links to Images and Videos. Repeat for each post and page having any image or video links.

  • For Dropbox hosted images:
    • Get a Dropbox developer access token from https://www.dropbox.com/developers/apps.
      • [ToDo: provide links to attributions on how to create a Dropbox account, get developer credentials, and how to create a Dropbox app to allow API access to dropbox]
    • Run $env:DropboxAccessToken = "<DropboxAccessToken>"
      • [ToDo: provide a link to a document describing how to access the ATAP Powershell BuildTooling modules]
    • Run $env:PSModulePath = "./;" + $env:PSModulePath
    • Run $results = ./Get-DropboxSharedLinks.ps1' -verbose -path "Dropbox-path-to-folder-having-images-and-videos-for-a-post"
    • Validate the references to images and videos in the post uses the latest link information returned by the Powershell script.
      • [ToDo: Write a script to automate link checking the document and the links from Dropbox]
  • For Google Photos hosted images:
    • [ToDo: write instructions and scripts for Google Photo hosted images]
  • For Microsoft Drive hosted images:
    • [ToDo: write instructions and scripts for Microsoft Drive hosted images]
• [ToDo: write a script that tests each image link in each page and post in the site. ]

Check internal links

Ensure that all links in the page or post that refer to anchor points within the same document, or to anchor points in other pages or posts, work correctly.

• [ToDo: (far future) All Headings in .md documents should include an explicit anchor point. Links to headers in .md documents should refer to the anchor point associated with that header. See also the many answers to this StackOverflow question Cross-reference (named anchor) in markdown for more insight into why explicit anchors are desirable. The reason for using explicit anchor points boils down to the inconsistency between site generators when making anchor points out of Markdown headings. Different static site generators create anchor points using slightly different formats. But if you create an explicit anchor point, and reference that, then the choice of a site generator is moot. But the drawback is that you have to decide how to format anchor points, and decide how to handle name collisions. So until this site gets an automation tool for creating and using explicit anchor points, we will rely on the Jekyll generator’s markdown header’s anchor point format. ]

In the Minimal Mistakes theme, the Markdown processor is specified as Kramdown. Kramdown has a setting auto_ids: true which creates an id attribute on the header. Details can be found in the SO question and “starfry’s” answer jekyll markdown internal links

| :zap: the anchor id IS case-sensitive, and Jekyll renders the anchor id in lowercase. Ensure the “link to a heading” is in lower-case. | |————————————————————————————————————————————————-|

• Example link to heading in the same document
• Example link to heading in a site page
• Example link to heading in a categorized post

Check Responsive Styling

The site should behave “responsively” across different size devices, e.g., phone screen, tablet, laptop, desktop monitor, and “wide monitor”. This is a traditionally hard test/check to implement with automated testing tools.

• [ToDo write a manual checklist how to test for responsive site layout including responsive tests for text spans]
• [ToDo (Far Future) write automated scripts to test/check this aspect of the site]

Check Scripts

If the site contains any JavaScript functions, these need to be checked.

• [ToDo: write a testing document that describes how to test each JS script / function incorporated into the site]
• [ToDo: write a script that tests each JS script / function incorporated into the site]

Check Security

It is very important to ensure that nothing in the site allows bad actors to violate its security. This is especially true of any site features that store persistent data.

• [ToDo: write a security document that describes how to test the site’s security for data-at-rest, and data-in-transit]
• [ToDo: write a security document that describes how to use secrets while developing the site]
• [ToDo: write a script that tests the site for Security]

Check Accessibility

Accessability features of the site allow people with vision issues to use aids in navigating the site. Accessability design ensure a good experience for people who use accessability aids.

Attribution:

• How to Automate Web Accessibility Testing
• Pa11y

• Pa11y needs a sitemap.xml, which is generated by jekyll-sitemap gem. Another option is Sitemap Generator (botMap).

• [ToDo: write a development and testing document(s) that describes how to design and test the site for Accessibility]
• [ToDo: write a script that tests the site for Accessibility]
• [ToDo: add Internet references for additional information on Accessible design]

Check Globalization and Localization

Globalization and Localization features of the site make it easier to produce translations of the site into other languages and cultures.

• [ToDo: write a development and testing document(s) that describes how to design and test the site for Globalization and Localization]
• [ToDo: write a script that tests the site for Globalization and Localization]
• [ToDo: add Internet references for additional information for Globalization and Localization as it applies to static Blog Post sites]

Check that the Release Candidate works on the Internet

The Release Candidate has to be tested “as if” it was publicly accessible from the Internet. This focuses on the availability of content that is served from locations other than the main site, e.g. images, JS libraries, and CSS libraries.

Setup ngrok

• See Getting Started with ngrok

Publish to Internet via ngrok

1. Run $env:JEKYLL_ENV = 'production'; bundle exec jekyll serve to ensure that _site has been built with no drafts and with Disqus comments enabled.
2. Run ngrok from a Powershell prompt.
3. Copy the ngrok link information that is displayed
4. Using multiple different computers and devices with multiple different screen sizes from multiple different geographic locations, evaluate the public site (ngrok link) against the criteria in Site Checks .

Stop the local Jekyll server and close the ngrok channel

Steps to publish a draft post

If the site release includes one or more posts to be published, follow these steps to move the post from its drafts state to the published state.

• [ToDo: write a document that describes how to move a post from draft to production]
• [ToDo: write a script that moves a post from draft to production]

1. Ensure the terminal’s cwd is at the root of the repo.
2. Run git mv _drafts/<name-of-post.md> _posts/<category>/yyyy-mm-dd-name-of-post.md . Remember that Jekyll expects posts names to be lowercase and - separated.
3. Ensure the file has been moved and renamed, to the correct category subdirectory, and the proper date prefix added.
4. Run bundle exec jekyll serve and validate the new post passes the Site Checks