Release Plan

This is the release plan for the CFDE training website. This plan has sections to address the different release management topics:

• Expected release frequency
• Release numbering and naming convention
• Locations for release documentation, repo etc
• Roles and responsibilities for the releases
• Release standard operating procedure (SOP)

Release Dates

Our current release dates are set to coincide with NIH deliverable dates which are due on the 15th of every month. Previous releases can be viewed on GitHub or on the training website Release page.

Release Title and Tag Format

Given the montly cycle, releases are named with the month and year.

Title: Month Year (e.g. October 2020)
Tag: Year.Mo (e.g. 2020.10)

Release Checklists

The .github directory contains actions, workflows, and templates with checklists for to ensure that tutorials and new website pages are error-free when released to the public. These inlude auto-assigning reviewers to PRs against dev and stable, adding a reviewer checklist to PRs, auto-building the mkdocs-based website, and drafting a GitHub relase.

Training materials should follow the formatting, organization, and layout details described in the training website style guide.

Submitting New Website Content

New content for the website should be submitted as a pull request against the dev branch following the steps below.

• Create a new branch off dev. Give the branch a descriptive name that briefly describes the new feature or content (e.g. add-unix-csv-lesson).
• Add content. Tutorials should follow the formatting described in the training website style guide.
• When ready for review, create a PR.
• If necessary, pull any recent additions to dev into the PR
• View the draft build of the website by clicking on the readthedocs check in the PR.
• Respond to reviewer comments. Reviewers are automatically assigned and given a checklist. You can request additional reviewers.
• After successul review, merge the PR into dev and delete the branch.

Tutorial PR Checklist

The PR author should ensure: - a descriptive title - title should describe PR changes that will be added to release notes - clean build logs - automated check for correct documentation build - colorblindness test https://www.toptal.com/designers/colorfilter/ - correct rendering of website (preview of their branch using autogenerated RTD link) - resolution of any merge conflicts - release label - it is important to tag with Training-Release and is required. You can also tag with month based label e.g.Oct-2020 which is optional. - PR type label - new for new content, feature for new features, fixes for updates and fixes to existing content - assignment to the appropriate project - project board for a given release for tracking - linking of related issues - if applicable

Note that for a PR to be included in the release notes, it needs to be associated with both the release label and the PR type label. It is also possible to add labels and edit titles after the merge but prior to the internal release deadline. For clarity, the PR title should include the tutorial name and main intent of the PR. - Example PR title for a new tutorial: Enabling/Javascript adding content chooser and integration of content tabs and superfences - Example PR title for fixes to existing tutorial: Rendering/Jekyll and Working/Branches learning objectives and pre-reqs added

Reviewer Checklist for PR

The reviewer checklist is included in the PR template. Following the PR to merge into dev, the reviewers must ensure the tutorials pass the checklist for:

• spelling and grammar
• successful run of all installation and code chunks
• sufficient explanation and details for the tutorial content - suggestions for inclusion of admonition boxes or additional resources for clarity
• code syntax and naming convention - ensure code chunks have a logical progression and clear explanations
• adherence of tutorial format to style guide
• functional links (inter and intra) - check the automated broken links check for clean build, suggest intra links if applicable
• accessible hyperlink text - meaningful text hyperlinked instead of default "click here"

Review Process

The review process is split between the two levels of merge. Individual branches get merged into dev and all the changes for a release are collectively merged from dev into stable which is the base for the public facing website.

Merge into dev from individual branches requires two reviews while merge into stable requires group approval. Currently, automated reviewer assignment has been implemented which assigns the correct number of reviewers depending on the merging branch. However, if a team member with experience in a tutorial topic is not assigned to review the tutorials, one can manually add an additional reviewer. Alternatively, that team member can offer their review in the form of comments on the PR. Reviewers can also be manually unassigned if necessary. While both the manually added and auto assigned reviewers will be notified via the GitHub notification, the PR author should make sure to communicate with the reviewers for timely review and any necessary clarifications.

Release Cycle

Each Release cycle will be defined as the time period between the releases. The release cycle will have some set phases:

• Tracking
• Planning
• Development
• Internal release deadline
• Final merge
• Public release

The overall workflow is visualized in the flow diagram of the release process.

Tracking

Using 'Projects' in GitHub we will create and track issues throughout the release cycle.

Planning

Each release cycle there are different tasks to be completed: - new tutorial development - fixes to existing tutorials - GitHub management - creating issues and labels - tracking - new tutorial reviews - general reviews - reviews for merge into stable - release notes maintenance

The planning phase scheduled following a release will allow for discussion and assignment of the different roles for the upcoming release. This phase will also include discussion for generating new content and creation of appropriate issues in the training repo.

Development

This phase will include work on developing new content and enhancing published tutorials.

• Authors developing new tutorials should allow for at least 1 week for the review process in their plans
• When possible include installation and setup steps across all target platforms (Mac, linux, Windows)
  • Provide links to setup instructions if they already exist as standalone tutorials
  • For overlapping setup instructions that are part of an existing tutorial, check if the setup instructions can be reorganized into standalone modules
• To ensure tracking and linking of related issues, the authors involved in tutorial creation or fixes should create related issues in the training-and-engagement GitHub repo and assign appropriate labels for the release.

Internal release deadline

Internal Release Deadline: five business/working days prior to release date

Checklist for internal release: - all PRs tagged for the upcoming release should be prepared for successful merge into dev and been successfully rendered. - the original PR author should ensure all review comments (if any) are addressed prior to merge. - all new tutorials should follow the style guide for formatting and tutorial arrangement. - if changes requested from a reviewer on a PR cannot be completed by the internal release deadline, the PR author should relabel with the next release date. - connect intra tutorials that were merged into dev if applicable

Final merge

This phase will involve merging dev into stable. Allotted timeline would be 5 business/working days until release date.

This phase will involve finalizing release-notes for the website. A draft of the release notes will be auto generated based on PR merges into dev.
To access the draft - access the Releases tab on the main repo page - click on Create a new release - subsequently click on Releases - use the Edit button on the right top corner - modify the release titles if applicable, add date and save draft

The release information will also be documented in a markdown file index.md, hosted within Release Notes folder under the /docs folder structure of the training repo in Github. For every new release, copy the existing contents within index.md to a new file with name {Month}-{year}.md before entering the latest release notes into index.md. Editing of the the website release version will include removing Website Features category, intra linking of tutorials mentioned and documenting changes to existing tutorials under the Updates and Fixes category. Addition of enhancements features like vidlets, images, screencasts etc to existing tutorials can be highlighted in a separate category (Enhancements or Improvements) if applicable.

The release notes will also be referenced in the landing page of the training website.

Merging from dev to stable requires group approval. For this phase, one PR will be opened for merge into stable and the approval for merge will be based on the rendered website with the following checklist: - If new features were merged check for functionality across entire site - Check for tutorial rendering on multiple browsers, modes (normal, incognito) and devices (phone, tablet, laptop) - Chrome - Safari - Edge - Firefox

Public release

After the creation of release notes and the successful merge of dev into stable we will announce the release on GitHub, Twitter, the website, and through the CFDE Newsletter.

Jose and Jeremy handle the newsletter while Titus and Amanda handle the twitter page for CFDE. All of them should be tagged and/or pinged after the release for appropriate announcements.

Release Documentation

The Github repo for the training website will host a release section and associated tag information.

For documentation version numbering system we will follow the release date convention. Thus our release tag would have the format: YYYY.MM

For example October 2020 release would have the tag 2020.10. This would follow the same convention as set for labels on GitHub repo.

When creating a tag associated with the release notes it is important to tag the correct version of stable branch. Else, since the default branch is dev, this will lead to dev being out of sync with stable. There are two ways to circumvent this, after the merge of dev into stable:

• Update Target for tag (Preferable)
  • Click the Edit option on the autogenerated release draft
  • Enter the tag format in the Tag version box
  • Set Target branch to stable
  • Click Publish release after checking for contents
  • This will create the public release visible on main repo page
• Update dev
• This option is in case the tagging was associated with dev without updating Target branch
• After the merge of dev into stable, create a PR to merge stable back into dev to ensure they are both in sync
• Alternatively, the dev branch can be respawned from stable but require admin permissions on the repo (ask Amanda or Titus)

Release format for the public website:

Latest Release

Updated Release.Month Release.Date, Release.Year

New Tutorials Links to new tutorials added in the current release

Improvements or Enhancements (optional)

Any enhancements to tutorials or website features. This would include any additional screencasts, vidlets, images that were added to tutorials and integrated website features

Updates and Fixes

This section will highlight any code or link fixes to existing tutorials in addition to any clarification notes and explanation that was added.

Step-by-step

Details for each of these components are described above. These are the basic steps for generating the training website's release notes!

Part 1 - Add new release notes to website

• make a new branch from dev
• copy contents of index.md in Release notes directory to a new markdown doc named with release Month-Year.md
• copy draft release notes from Github Releases page to the index.md file and edit
  • remember to edit yaml title, page title with current release month/year
  • add links to the website pages using relative file paths
  • edit the .pages file in reverse chronological order so most recent release files on top
• create a PR to dev, merge after approved

Part 2 - PR of dev to stable

• merge after approved

Part 3 - Edit release notes for Github repo

• go to the draft release notes from Github Releases page and click "Edit draft"
• For the Tag version, enter the release YYYY.MM format and then specify the branch to tag. Switch the tag branch from dev to stable:
• add date in the "Updated on" release notes title (i.e., "Updated on February 24, 2021")
• click "Publish"!

Part 4 - PR of stable into dev

• merge after approved

---

Last update: June 22, 2022