📛 Improving a GitHub Repo!

I have been using GitHub for a long time and I spent time on a daily basis reviewing repos in the Open Source space. One of the most important things , from my point of view, is to get a good overview of the repository, a good documentation, but also good highlights, such as releases, status of the project, Changelogs, Contribution Guides, emojis (why not?) … so I can get faster a good summary of the repository. This is not easy and there are many different ways to do it, but I found some of them very easy to add in any repository.

This post covers two of these mechanisms to improve any GitHub Repository:

• 📛 Repository Badges
• ✅ Changelogs and 🤖🚩automatic releasing process

📛 Repository Badges

How does it look like a repo with badges? Something like this:

Nice 🫶, right?

Badges are an easy way to summarize a repo with information about topics such as building, test results, license, pipelines or workflows, versions, … This information provides quality metadata coming from many different resources. So meanwhile you are browsing, you get all this information in a single view. Incredible!

I found a simple way to integrate almost any badge in my repository …Shields.io. It is a service providing badges in different formats to integrate in GitHub readme files. This service supports a bunch of continuous integration services, package registries, distributions, app stores, social networks, code coverage services, and code analysis services (anything else? 🤷🏽‍♀️).

In short, using the web site you can customize your badge to your own requisites and 3rd party services, getting a code to add in your GitHub readme easily.

For example, the previous image is rendered using the next entries in my readme file of my Blog site repository:

![License](https://img.shields.io/github/license/rmarting/rmarting.github.io?style=plastic)
![Main Lang](https://img.shields.io/github/languages/top/rmarting/rmarting.github.io)
![Languages](https://img.shields.io/github/languages/count/rmarting/rmarting.github.io)
![Last Commit](https://img.shields.io/github/last-commit/rmarting/rmarting.github.io)

Easy ✅, and powerful 💪! So, don’t forget to add your badges in your repo to help me, and others 🤗!

✅ Changelogs and 🤖🚩automatic releasing process

Changelog, as a comprehensive and up-to-date file, is crucial for effective project management and collaboration. A changelog serves as a documented record of all the notable changes, enhancements, and bug fixes made to your software over time. It not only provides transparency and accountability but also facilitates communication among team members and external contributors. This file enables users and developers to easily track the evolution of the project, understand the latest features and improvements, and quickly identify any potential issues or compatibility concerns.

Getting all these benefits require a regular updating of that file, usually after releasing a new version or iteration of our software. But, how to track all the changes between versions? Who should do it? When? … It seems that it could be tedious every time if we have to do it manually … we can forget something to add, or we can forget to update it at all.

As fan of …

There is a way to automatically update the changelog file every time a new version is released. This blog post summarizes this process.

Step 1️⃣ - Create your Changelog file

Create a file, usually called CHANGELOG.md, with the following content:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

To delve deeper into the significance of changelog files and learn about best practices for creating and maintaining them, I recommend checking out Keep a Changelog. This resource offers a comprehensive guide and industry-accepted standards for crafting informative and well-structured changelogs.

Step 2️⃣ - Use a Release workflow to publish new releases

The Release Drafter GitHub Action is an incredible GitHub action to automate a new release of the repository. The action is initially designed to draft a new release, but it is also valid to release automatically the version. In my case, I will automatically release the version as soon as a new tag is pushed.

The following release-drafter.yml file inside of the .github/workflows folder will publish a new release after a new tag is pushed into the repository. The tag must be aligned with theSemantic Versioning:

name: 🔖 Release Drafter 🔖

on:
  push:
    tags:
      - v[0-9]+.[0-9]+.[0-9]+

permissions:
  contents: read

jobs:
  update_release_draft:
    name: Release drafter
    runs-on: ubuntu-latest
    permissions:
      # write permission is required to create a github release
      contents: write

    steps:
      - name: Update Release Draft
        uses: release-drafter/release-drafter@v5
        with:
          publish: true
          prerelease: false
        env:
          # Instead of GITHUB_TOKEN Ref: https://github.com/stefanzweifel/changelog-updater-action/discussions/30
          GITHUB_TOKEN: $

The publish: true attribute publishes the release as final, just because the prerelease attribute is marked as false.

Step 3️⃣ - Format the Release content

The content of the release will include information coming from the different pull request, issues, and commits. This information can be included automatically into the release notes using different patterns. These patterns are described in the release-drafter.yml file inside .github folder:

The following example is a full example using different categories of information to add into the release notes.

# This release drafter follows the conventions from https://keepachangelog.com

name-template: 'v$RESOLVED_VERSION'
tag-template: 'v$RESOLVED_VERSION'
template: |
  ## What Changed 👀

  $CHANGES

  **Full Changelog** : https://github.com/$OWNER/$REPOSITORY/compare/$PREVIOUS_TAG...v$RESOLVED_VERSION
categories:
  - title: 🚀 Features
    labels:
      - feature
      - enhancement
  - title: 🐛 Bug Fixes
    labels:
      - fix
      - bug
  - title: ⚠️ Changes
    labels:
      - changed
  - title: ⛔️ Deprecated
    labels:
      - deprecated
  - title: 🗑 Removed
    labels:
      - removed
  - title: 🔐 Security
    labels:
      - security
  - title: 📄 Documentation
    labels:
      - docs
      - documentation      
  - title: 🧩 Dependency Updates
    labels:
      - deps
      - dependencies
    collapse-after: 5

change-template: '* $TITLE (#$NUMBER)'
change-title-escapes: '\<*_&' # You can add # and @ to disable mentions, and add ` to disable code blocks.

exclude-labels:
  - skip-changelog

Step 4️⃣ - Update Changelog file

After a new version is released, we want to update the changelog with the latest changes, as we are doing with the release notes. We can automate it using another amazing GitHub Action - Changelog Updater.

This action can be integrated into another workflow (i.e: update-changelog.yml inside of the .github/workflows folder). This workflow can be similar to:

name: 📄 Update Changelog 📄

on:
  release:
    types: [released]

jobs:
  update:
    name: Update Changelog
    runs-on: ubuntu-latest
    permissions:
      # Give the default GITHUB_TOKEN write permission to commit and push the 
      # updated CHANGELOG back to the repository.
      # https://github.blog/changelog/2023-02-02-github-actions-updating-the-default-github_token-permissions-to-read-only/
      contents: write    

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Update Changelog
        uses: stefanzweifel/changelog-updater-action@v1
        with:
          latest-version: $
          release-notes: $

      - name: Commit updated Changelog
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          branch: main
          commit_message: '🔖 Update changelog'
          file_pattern: CHANGELOG.md

So, this workflow will start when a new release is released (types: [released]), including the changes from previous release and committing the change into the main branch of our repo.

Step 5️⃣ - Linking release and update changelog workflows

There is an issue reported hereabout how to automatically trigger the update changelog workflow from the release workflow. The workaround to fix it requires adding a new secret (i.e: PERSONAL_ACCESS_TOKEN) into your repo:

Step 6️⃣ - Release a new version

Now, it is very simple, just follow your development workflow, using your pull-request life cycle, add the labels of your own repository, and then tag a new version when you are ready to do it.

Push it into your repo:

git tag v1.2.1 -m "Version 1.2.1"
git push origin v1.2.1

The workflows run as expected:

… a new release is created, including the notes:

… and the changelog is updated too:

This is …

🤖🚩 Happy automating releasing!!! 🤖🚩

References

This blog post is my own summary about this process, but it was based from the content and experience of others, such as:

• Stop writing your changelogs manually
• Release Drafter GitHub Action
• Changelog Update GitHub Action

My kudos ❤️ to all of them!!!