Doka is a Russian web developer's newest open-source handbook. We are new, so we had to create our workflow from scratch. We are demanding labels users, and we can hook you up too!
Problem
When a project has a sophisticated multi-stage review process, the workflow quickly goes out of hand - pull requests get lost, and the review time grows, leading to unhappy contributors.
For example, In Doka's case, we have four sections of our website, each with a dedicated editor: HTML, CSS, JS, and tools. On top of that, there is a responsible for demos, an illustrator, and a publishing editor. We wanted to have one place where they can go to understand what job is pending.
In most of the repos, you probably want to know:
- the scope a particular PR has;
- what parts of the project it touches;
- whether it removes or edits files you don't want to be touched.
Options
What are the options Github gives us? There are not many: codeowners and labels.
Codeowners
Assignee and reviewers are similar. Somebody assigns a person responsible for the PR, and you can filter the list by your name.
Reviewers can even be automated using a CODEOWNERS file at the root of the project. Code owners are defined based on files and have to get approval from the owner.
The significant advantage of that approach is that the reviewer gets notifications about the PR.
However, the more code you have, the more complicated the file becomes. It also bloats the notification panel because you automatically watch every PR you were assigned to.
Labels
Labels are a non-restrictive approach to marking PRs, and they do not require anything from your side to provide insights about the PR content.
We found they are a great companion of code owners when cooked well. The label-scoped pull requests and issues have a unique filter URL, which a person can bookmark and see only their scope of work.
However, you need to be careful to not create too many, making them impossible to grasp and use by contributors.
The standard approach is to label PRs by task type (bug, feature, question, etc.) and by complexity (internal, good first issue).
We decided to add more essential labels:
- scope - module, section, component;
- type work needed - design review, editor check, or demo creation;
- restricted files touched — e.g., removed
package-lock.json; - add your project-specific labels - we also add a label that reflects the
tagkey from markdown files' frontmatter.
Solution
We took the best from both worlds and followed the approach we found extremely useful:
- Define code owners for parts that are critical, no less than two people per section;
- Provide additional information automatically through labels.
We couldn't find the best automatic labeler, so we wrote it ourselves. With it, you can automate both sides of the equation. It has built-in core modules:
- label PR based on file paths in a PR and their status (added, removed, renamed, modified);
- assignee;
- front matter from any statically generated engine (we use 11ty)
You can add yours!
doka-guide
/
doka-labeler
An action for automatically labelling pull requests
Doka Labeler
Automatically label pull requests based on multiple criteria with minimal configuration:
- files added, deleted, renamed, or modified
- assignees
- front matter of markdown files
- your custom rules
Example
Set "design review" label if PR contains a new HTML file in the src folder:
"design review":
files:
added: src/**/*.html
Comparison with other labelers
- Doka Labeler — set labels PRs based on files and their statuses, assignees, front matter, and more with readable configuration.
- Official Github Labeler — can assign labels by file path presented in the PR. Cannot assign labels based on file status.
- PR Labeler — assign labels based on branch name.
- Label Mastermind — can do everything, but has a complex configuration
Getting Started
Create Workflow
Create a workflow (eg: .github/workflows/labeler.yml see Creating a Workflow file) to apply the labeler for the repository:
name: Labeler
on
push:
branches:…Example
Let's consider a blog where posts are placed in the posts folder. Each post can be either an article or a daily log which is defined in the tags front-matter key (as in dev.to).
We want to label PRs:
- with the type of post it contains;
- as "needs design review" when a new image is added;
- an alarming label when critical files are removed.
Here is how we can organize it using Doka Labeler.
Create workflow
Create a workflow definition file at .github/workflows/labeler.yml
labeler.yml
name: Labeler
on:
push:
branches:
- main
pull_request:
branches:
- main
workflow_dispatch:
jobs:
labeling:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Run labeler
uses: doka-guide/doka-labeler@v1
with:
token: "${{ secrets.GITHUB_TOKEN }}"
config: ".github/labeler-config.yml"
Define labeling rules
Create a config file at .github/labeler-config.yml:
labeler-config.yml
# set "article" label when front matter has "article"
"article":
- meta:
tags: "article"
# set "daily log" label from front matter:
"daily log":
- meta:
tags: "daily-log"
# "design review" if images are added or modified:
"design review":
- files:
added: *.(jpg|jpeg|svg|png)
modified: *.(jpg|jpeg|svg|png)
# alarm when critical files are removed
"🚨 alarm":
- strategy:
- create-if-missing # create this label if it does not exist
- files:
modified:
- package-lock.json
removed:
- package-lock.json
- package.json
- .github/**
We have more examples in the repository!
Submission Category:
Maintainer Must-Haves
Gratitude
People:
Libraries used:
- Checkout Action
- Picomatch instead of minimatch
- front-matter parser
- Vercel's ncc compiler
Top comments (0)