Canvas LMS Github Repository Tutorial
Canvas deploys contain code changes that are intended to fix bugs, improve performance, and prepare for new features. They do not affect customer workflows. These deploys take place every two weeks. Intended changes in workflow are noted in the monthly Canvas Release Notes.
Notable entries for the main Canvas deploy will be available as deploy notes on the same day as the production deploys. However, deploy notes are not meant to be an exhaustive list of all fixed behaviors, as some may not be included. For more details, visit the Canvas Deploy FAQ.
Customers with a greater interest in the full deploy can access the open-sourced canvas-lms Github repository. The repository displays all code deployed to Canvas master, beta, and production environments.
Github Glossary
Github users should become familiar with some common terms used for the Canvas LMS repository as referenced from the Github glossary.
Repository: A repository contains all files for a project and stores each file's revision history. Repositories can have multiple collaborators and can be either public or private. The Canvas LMS repository is public and has had several hundred contributors and collaborators.
Collaborator: A collaborator is someone who has direct access to manage a repository. Collaborators to the Canvas LMS repository are most commonly Canvas software engineers.
Contributor: A contributor is someone who has contributed to a repository and has asked to have a commit merged into the master branch. Contributors to the Canvas LMS repository most commonly are open source users who are not employed by Instructure.
Branch: A branch is a parallel version of a repository and an independent line of development. Branching allows contributors to check out code from the default branch, work on their own projects, and then merge their code back into the default branch. Branching keeps their work isolated so that they do not disrupt the live version of the code. The Canvas LMS repository has three branches: Master (the default), beta, and stable (the live version).
Commit: A commit is an individual change to a file (or set of files) merged into the default branch. Each commit includes a description about the file(s), what changes were made, and the collaborator who made the changes. A collection of commits can be deployed together in a release.
Canvas LMS Repository Page
The Canvas LMS repository page defaults to the Code tab, which displays all up-to-date code files for the Master branch. This view is helpful if you want to clone the repository for a specific branch or view a specific source file.
However, if you’re just trying to look for commits, view the Commits link, which loads the Commits page.
The Commits page displays all commits associated for a specific branch.
Commits can be viewed by branch or tags.
Branches
In the Canvas LMS repository, code is deployed from the Master (Default) branch to the Beta branch, then to the Stable branch.
Selecting the Branch menu allows you to select a specific branch and see all the existing commits deployed to the branch.
Master Branch
When code from contributors and collaborators is ready for review and checked against all internal QA processes, the code can be merged into the Master branch and become part of the code base. All code merged into the Master branch will become part of the next scheduled beta deploy.
Beta Branch
The Beta branch is updated from the Master branch every other Thursday (every 14 days). Code that is updated into the Beta branch outside the regularly scheduled deploy is called a warmfix. Code can be warmfixed after QA approval and may be requested when needed to place the code in the production environment earlier than anticipated, such as to resolve a bug fix earlier or correct functionality before it is deployed to the stable branch.
Stable Branch
The Stable branch represents the code as it is in the live environment. The live environment for Canvas is called the production environment.
Code can be picked directly from the Master branch to the Stable branch at any time when needed, such as when quickly correcting a significant problem on the production environment. This code is validated by Instructure by way of a separate internal staging environment before being deployed to production. Code that is updated into the Stable branch outside the regular deploy is called a hotfix.
Stale Branches
The Branch menu includes two additional branches: private and release/2016-04. These branches are stale and are not active in the repository.
Tags
Tags indicate a snapshot of a period of time when commits were deployed to a specific environment. In the Canvas LMS repository, tags are organized by the most recent release and align in numerical order. Release indicate the date associated with the deploy.
For instance, a tag noted release/2019-07-31.15 indicates the 15th update added to the 2019-07-31 deploy.
Tags are helpful for open source customers or customers managing their own code updates. Although Canvas does not use traditional versions, tags can help these customers keep track of which code deploy they have updated for their accounts.
Note: Github release terminology is not the same as used for Canvas releases, which take place the third Saturday of each month. Code for an upcoming release may be shown in a Github commit list, but because of feature flag associations, the code will not be usable in Canvas until the intended Canvas release date.
If needed, you can select a specific tag to view the most recent commits at the time of the created release tag. You can select a tag in the Tag menu.
Tag Comparisons
If you need to view the difference in code commits between release tags, you can compare the most recent commit dates displayed for the selected release. For instance, comparing the release/2019-07-31.15 and release/2019-07-31.12 tags indicates a date difference between July 30 and July 25.
Tag results can also be loaded by adding /tree/release/TAG-DATE to the browser URL (e.g. https://github.com/instructure/canvas-lms/tree/release/2019-07-31.10.
However, the easiest method of comparing changes between specific dates is using branches, as noted in the next section.
Branch Comparisons
You can compare different branches to compare changes in commits and files.
To compare changes, visit the Compare Changes page (or add /compare to the browser URL).
In the Base menu, select the base branch. In the Compare menu, select the branch you want to compare.
Common comparisons are as follows:
Beta to Master Branch Comparison
Use this option to compare the number of changes in the master environment that will be deployed to the beta environment as part of the next scheduled beta deploy.
- In the Base menu, select the Beta option.
- In the Compare menu, select the Master option.
Stable to Beta Branch Comparison
Use this option to compare the number of changes in the beta environment that will be deployed to the stable (production) environment as part of the next scheduled production deploy.
- In the Base menu, select the Stable option.
- In the Compare menu, select the Beta option.
Self Branch Comparison via Time Period
Use this option to view more granularity in the same branch within a specific time period, such as days or weeks. This option allows an easy comparison to view commits updated in a branch without knowing an exact deploy date.
To specify a time period, click the Base menu. In the text field, type in the name of the branch, followed by an @ symbol and a set of curly brackets {}. Between the brackets, enter the time period you want to compare. The time period option will become a selectable option in the menu. Select your option, and the page will generate the results.
You can also set time periods for the Compare menu as well.
Example Comparisons
Base |
Compare |
Result |
beta@{2days} |
beta |
Compare current beta environment against beta as it was 2 days ago |
beta@{15days} |
beta |
Compare current beta environment against beta as it was 15 days ago |
beta@{24hours} |
beta |
Compare current beta environment against beta as it was 24 hours ago |
beta@{5days} |
beta@{2days} |
Compare current beta environment 2 days ago against beta as it was 5 days ago |
beta@{07-22-19} |
beta |
Compare current beta environment against beta as it was on July 22 |
Once the query is complete, the page displays the results, if any. Some comparisons may not exist if the results are identical.
Commit Details
To quickly view details for a commit, hover over the commit message. The commit message provides a quick summary of the action in the commit.
Details of the message can also be expanded and hidden by clicking the Options menu next to the message.
Each commit includes a test plan with a walkthrough for replicating the behavior.
GitHub Help
For additional help with GitHub or questions about open source Canvas, visit the Canvas Developers group in the Canvas Community or Canvas Dev & Friends.