Skip to main content

​
Git Workflow

Kolibri follows the Gitflow branching model at a high level. This provides a structured approach to managing features, releases, and hotfixes.

​
Helpful References

​
Branch Structure

Within the Learning Equality Kolibri repository:
  • develop: The current development branch and the default target for pull requests
  • Release branches: Named like release-v1.2.x (e.g., release-v1.2.x tracks all patch releases within the 1.2.x minor release line)
  • Feature branches: Sometimes created for changes that are long-running, collaborative, and disruptive. These should be kept up-to-date with develop by merging, not rebasing
If a change needs to be introduced to an older release, target the oldest release branch that needs the change. Then that change will need to be merged into all subsequent releases, one-at-a-time, until it eventually gets back to develop.

​
Development Phases

Kolibri has the following release types:
  • Final: Public releases (e.g., v1.2.3)
  • Beta: Final integration testing, string freeze, and beta release candidates (e.g., v1.2.3-beta4)
  • Alpha: Initial testing releases (e.g., v1.2.3-alpha4)
  • Dev: Feature branches, PRs, or other git commits (experimental work is OK)

​
Pull Requests

​
Creating a Pull Request

Developers maintain their own clones of the Kolibri repo in their personal GitHub accounts, and submit pull requests back to the Learning Equality repo.
Be sure to follow the instructions shown in the GitHub PR template when you create a new PR.

​
PR Labels

Please use the following labels mutually exclusively to communicate the state of the PR:
  • “Needs review”: PR is ready for review
  • “Work in progress”: PR is not yet ready for review
  • “Needs updates”: PR requires changes based on review feedback
Keep these labels mutually exclusive and up-to-date throughout the PR lifecycle.

​
PR Requirements

Every pull request will require some combination of:
  • Manual testing
  • Code review
  • Automated tests (all must pass)
  • Gherkin stories
  • UI design review
Developers must fully test their own code before requesting a review, and then closely follow the template and checklist that appears in the PR description.

​
Testing Requirements

Unit tests and gherkin stories should be written to ensure coverage of critical, brittle, complicated, or otherwise risky paths through the code and user experience. Intentional, thoughtful coverage of these critical paths is more important than global percentage of code covered.

​
Best Practices for PRs

Try to keep PRs as self-contained as possible. The bigger the PR, the more challenging it is to review, and the more likely that merging will be blocked by various issues.
Additional guidelines:
  • Submitters should fully test their code before asking for a review
  • If the PR is languishing, feel free to prod team members for review
  • Try to keep the PR up-to-date with the target branch
  • Make sure to use the checkboxes in the PR template

​
Git History

Within the Kolibri repo, we have the following primary rule:
Never rewrite history on shared branches.
History has been rewritten if a force push is required to update the remote. This will occur from e.g. amending commits, squashing commits, and rebasing a branch.

​
Additional Git History Guidance

  • Be encouraged to rewrite history on personal branches so that your git commits tell a story
  • Avoid noisy, meaningless commits such as “fixed typo”. Squash these prior to submitting a PR
  • When possible, make each commit a self-contained change that plays nicely with git bisect
  • Once a PR code review has occurred, avoid squashing subsequent changes as this makes it impossible to see what changes were made since the code review
  • Don’t worry too much about a “clean” commit history. It’s better to have some messy commits than to waste an hour debugging a rebase-gone-wrong

​
Code Reviews

When reviewing PRs, keep feedback focused on critical changes. Lengthy conversations should be moved to a real-time chat when possible. Be polite, respectful, and constructive.
We highly recommend following the guidance in this blog post.

​
General Guidelines for Reviewers

  • Reviewers should actually run and test the PR
  • Clarify blocking vs. non-blocking comments: When giving opinions, clarify whether the comment is meant to be a “blocking” comment or if it is just a conversation
  • Pre-existing issues or other cleanup suggestions can be opened as new issues, or mentioned as “non-blocking” comments
  • Code formatting comments should be rare because we use Prettier and Black

​
Pushing to PR Branches

If you see a very trivial but important necessary change, the reviewer can commit the change directly to a pull request branch. This can greatly speed up the process of getting a PR merged.
Pushing commits to a submitter’s branch should only be done for non-controversial changes or with the submitter’s permission.
Git LFS Bug Workaround: When pushing to another user’s branch, you may get an error like: 
Authentication required: You must have push access to verify locks
This is due to a Git LFS bug. Try disabling lock verification using the lfs.[remote].locksverify setting, or simply running: 
rm -rf .git/hooks/pre-push

​
Merging PRs

​
Who Should Merge?

First, all automated checks need to pass before merging. Then:
  • If there is just one reviewer and they approve the changes, the reviewer should merge the PR immediately
  • If there are multiple reviewers or stakeholders, the last one to approve can merge
  • The reviewer might approve the PR, but also request minor changes such as a typo fix or variable name update. The submitter can then make the change and merge it themselves, with the understanding that the new changes will be limited in scope
  • Stale reviews should be dismissed by the PR submitter when the feedback has been addressed

​
GitHub Labels

We use a wide range of labels to help organize issues and pull requests in the Kolibri repo.

​
Priority Labels

These are used to sort issues and sometimes PRs by priority if and only if the item is assigned a milestone. Every issue in a milestone ought to have a priority label. Only ‘critical’ items are strictly blockers for a release, but typically all important items should be expected to make it in, too.
  • P0 - critical
  • P1 - important
  • P2 - normal
  • P3 - low

​
Other Useful Labels

  • changelog: Used on PRs or issues to generate ‘more details’ links in the changelog
  • work-in-progress: Helpful if you have a PR open that’s not ready for review yet
  • DEV:: Labels prefixed with DEV: are used to help organize issues (and sometimes PRs) by area of responsibility or scope of domain knowledge necessary
  • TODO:: Labels prefixed with TODO: help flag items that need some action before the issue or PR can be fully resolved
  • TAG:: Labels prefixed with TAG: are general-purpose, and are used to help organize issues and PRs
The project as a whole is released under the MIT license, and copyright on its code is held by multiple parties including Learning Equality. Individual files, such as code copied in from other projects may be under a different license, if that license is compatible. Similarly, files from Kolibri may end up being copied into other projects. For these reasons, copyright and license data may be listed explicitly at the top of some files. For example: 
# Copyright 2023 Ann Contributor
# SPDX-License-Identifier: MIT
This format is machine readable and complies with the REUSE specification for software licensing.
For files where the license is not explicitly stated, the overall project license applies.

Build docs developers (and LLMs) love

Get started for freeTalk to us