Maintenance Processes

Issue and PR Triage

Issue triage should be handled regularly (recommend short daily sessions or longer weekly sessions) to keep response times low.

We use an open-source tool called Triage Party to triage GitHub issues and PRs. This provides a unified view of issues across all of our repositories. Though it is meant for maintainers, it is accessible to anyone, and does not have any write permissions to any repos.

Our Triage Party instance provides views that are scoped to specific groups of projects:

You can navigate between projects using the headings in the top-left:

Within each project, there are tasks for triage, fixing bugs, and cleanup. By default, you get collections associated with triage. You can navigate between tasks by clicking the headings in the top-right:

The issues in the triage collections should be investigated in order. For example, "untyped issues" should have their type set (type: bug, type: enhancement, type: question, etc.), then "unprioritized issues" should have a priority label set (priority: P1, priority: P2, etc.)

Each task has a description, and each issue in that list can be clicked to open a new tab to the issue on GitHub. Tasks can be collapsed by clicking on the heading.

Our triage party instance is customized, configured, built, and deployed from shaka-project/triage-party-config. Any time changes are merged to the main branch, the instance is automatically updated through Google Cloud Build and deployed to Google Cloud Run.

Versioning

Semantic Versioning

Shaka Player uses semantic versioning for releases (see semver.org). This is expected for packages in the JavaScript ecosystem, and is generally understood by developers.

Version numbers have three numeric components separated by dots, and an optional prerelease tag. Versions look like this: MAJOR.MINOR.PATCH, and the rules can be summarized as:

Increment MAJOR when you make incompatible API changes,
Increment MINOR when you add functionality in a backwards compatible manner,
Increment PATCH when you make backwards compatible bug fixes.

Unless otherwise noted (for a specific project), release versioning is automated as part of the release workflow.

Conventional Commits

Conventional Commits is a syntax for commit messages that helps automate semantic versioning (see conventionalcommits.org). In short, every commit message should begin with a commit type and a colon, such as "fix: ..." for backward compatible bug fixes, "feat: ..." for backward compatible features, or "feat!: ..." for a breaking change.

The automated release workflow will parse these commit messages to determine what the release version should be. If no features have been added, the PATCH number is incremented. If only backward compatible features have been added, the MINOR number is incremented. If breaking changes have been added, the MAJOR number is incremented. See the rules for "Semantic Versioning" above.

PR Process

PR titles and descriptions should follow Conventional Commits syntax. This is enforced already by GitHub Actions for most of our repositories (excluding non-releasing repos for things like infrastructure).

If a PR title does not meet the requirements, a required check will fail and the PR cannot be merged. As a maintainer, you can simply edit the PR title, and the check will be run again.

This ensures that PR commits follow Conventional Commits syntax, which will in turn drive the generation of changelogs and releases.

Release Process

Releases are generally automated through a tool called Release Please. A GitHub Action will watch the commit messages of all new changes to the main branch or configured release branches, and automatically generate or update a release PR. This PR will update version numbers and changelogs.

Version number changes respect Semantic Versioning, based on Conventional Commits syntax in the commit messages. See "Versioning" above.

To start the release process, just approve and merge the automated release PR. The Action will run again, this time creating tags and GitHub releases, as well as any NPM, PyPi, or other releases necessary.

NOTE: Our release PRs do not automatically trigger the PR title check. (We don't know why not.) To get the title check to run, you may need to approve the PR or make a no-op change to the title.

NOTE: The following repositories have not yet adopted the release automation described here:

Shaka Streamer

Fixing Release Notes

If you merge a PR and want to fix the release notes for it before release, you can edit the PR description and append an "override" block. This is a feature of Release Please.

Example:

BEGIN_COMMIT_OVERRIDE
feat: add ability to override merged commit message

fix: another message
chore: a third message
END_COMMIT_OVERRIDE

Upstream documentation: https://github.com/googleapis/release-please#how-can-i-fix-release-notes

Automated Maintenance

See also these automated systems which are widely deployed across our repos:

Per-Project Processes

Shaka Player

TODO: Add more per-project process docs.

This site is open source. Improve this page.