DEV Community

Liran Tal
Liran Tal

Posted on • Updated on

The maintainer's CI workflows recipe for a peaceful open source life

My Workflow

My GitHub Actions hackathon application entry is about all the small things that would contribute to a better maintainer life.

Maintainers usually get a good grip on the important things, like making sure they have a workflow that run code style checkers, tests, and that publishes a package to the registry.

Busy with these, they end up forgetting about the small things that are the details, but as important, for example: having a markdown linter in place to ensure no broken documentation.

Can we reach open source maintainer nirvana?
I can't promise you that, but I can promise I will do everything I can to put us on that direction.

With that in mind, I'm suggesting a recipe of several GitHub Actions CI workflows that you can add to your open source repositories at GitHub. I've segmented them into specific areas too.

Markdown documentation

This recipe will introduce the following workflows:

  • Markdown Style linter - Making sure your documentation like the README.md has proper
  • Markdown Links linter - Making sure your documentation has no broken links

Dependency management

  • New dependencies advisor - Add a comment in a Pull Request informing of newly added dependencies and their package health

Pull Request engagement

  • Pull Request title update - Do you manage multiple base branches with PRs to? If you manually updated your PR titles to include this information then now this is automated for you

  • Pull Request contribution fun note - Welcome contributors to your project by adding a comment that thanks them and embeds an image of a cute animal

Submission Category:

  • Maintainer Must-Haves

Repository

The following repository demonstrates the workflow this application suggests:

GitHub logo lirantal / github-actions-hackathon-actionshackathon21

Repository for GitHub Actions Hackathon on Dev.to 2021 [actionshackathon21]

github-actions-hackathon-actionshackathon21

Repository for GitHub Actions Hackathon on Dev.to 2021 [actionshackathon21]




Additional Resources / Info

The recipe makes use of the following GitHub Actions from the marketplace:

Demo

Let's put all of it together and see how they add to an overall better experience for both maintainers and contributors alike.

Pull Request title update

PR title update with base branch

As you can see, a few minutes after creating the pull request, the action kicks in and updates the title so that it includes a base branch prefix (the text [main]).

To make that magic happen, we create a brand new GitHub Action workflow file and add this:

name: "PR title update with base branch"
on: [pull_request]

jobs:
  pr_title_update:
    runs-on: ubuntu-latest
    name: "PR title update with base branch"
    steps:
      - name: "PR title update with base branch"
        uses: lirantal/github-action-pr-title-update-branch@main
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

Pull Request contribution fun note

Pull Request contribution fun note

Ain't it cute to get that nice little note? I think so too ;-)

To make that magic happen, we create a brand new GitHub Action workflow file and add this:

Enter fullscreen mode Exit fullscreen mode

New dependency advisor

I can't stress enough how important is making sure you are using healthy dependencies, and those without security vulnerabilities. How can you tell if a new one someone adds to your project is a liability or a gift?

Image description

Luckily, we have the Snyk Advisor, and this handy GitHub Action helping us vet it:

name: "Deps: show dependencies metadata"
on:
  - pull_request

jobs:
  deps_check_new_dependencies:
    runs-on: ubuntu-latest
    steps:
      - name: "Checkout repo for a local instance"
        uses: actions/checkout@v2

      - name: "Deps: show dependencies metadata"
        uses: lirantal/github-action-new-dependencies-alerts@v1.1.0
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

Markdown Style linter

If a markdown file doesn't confirm to proper style conventions then we can find out about it in the Pull Request CI phase rather than after we see it "in production", or in other words, showing up to the whole world as the face of the repository:

Image description

To make that magic happen, we create a brand new GitHub Action workflow file and add this:

on:
  push:

name: "Markdown: style"
jobs:
  markdown_lint:
    name: "Markdown: style"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: "Markdown: style"
        uses: ruzickap/action-my-markdown-linter@v1
        with:
          config_file: .github/markdown-style-config.yml
          #debug: true
          search_paths: |
            ./
            docs/
          exclude: |
            node_modules/
            coverage/
            dist/
            tests/
            CHANGELOG.md
Enter fullscreen mode Exit fullscreen mode

And make sure that you have the accompanying configuration file for it as such:

# Default state for all rules
default: true

# MD033/no-inline-html - Inline HTML
MD033:
  # Allowed elements
  allowed_elements: ['p', 'br', 'h1', 'h2', 'h3', 'h4', 'a', 'img']

# Don't fail on line length limit of 80 chars
MD013: false

# Don't fail on first line of the file not being a markdown heading (maintainers like beautiful READMEs)
MD041: false
Enter fullscreen mode Exit fullscreen mode

Markdown Links linter

Want to avoid broken links in your README? Me too

That's why I can now find out about it when it happens in the CI process when I push a change via a pull request rather than after the fact:

Image description

To make that magic happen, we create a brand new GitHub Action workflow file and add this:

on:
  push:

name: "Markdown: broken links"
jobs:
  markdown-link-check:
    name: "Markdown: broken links"
    runs-on: ubuntu-latest
    steps:
      - name: "Checkout project"
        uses: actions/checkout@v2

      - name: "Markdown: broken links"
        uses: ruzickap/action-my-markdown-link-checker@v1
Enter fullscreen mode Exit fullscreen mode

That's it, have fun!

Discussion (3)

Collapse
lirantal profile image
Liran Tal Author

Also, discovering this welcome-new-contributor style GitHub Action has been very fun github.com/marketplace/actions/ani... :-)

Collapse
circa10a profile image
Caleb Lemoine

Glad you like it! 鉂わ笍

Collapse
lirantal profile image
Liran Tal Author

I created a new GitHub Action and added it as part of the recipe: - lirantal/github-action-new-depende...