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 tag key from markdown files' frontmatter.

Solution

We took the best from both worlds and followed the approach we found extremely useful:

1. Define code owners for parts that are critical, no less than two people per section;
2. 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:

…

View on GitHub

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

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:

# 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:

Igor KorovchenkoFollow

My first code was on Basic in September 1990. During 3 years after 1992 I hadn't any opportunity to write a code. But from the end of 1995 I started...

Nik LopinFollow

Teaching, mentoring, edtech, mobility and fast web. 10+ years in IT, in various positions: engineer, tech lead, engineering manager, and product owner.

Libraries used:

• Checkout Action
• Picomatch instead of minimatch
• front-matter parser
• Vercel's ncc compiler