For the second part of my Release 0.3 contribution to the faker-cxx project, I addressed an issue involving the addition of a Continuous Integration (CI) pipeline. The goal was to ensure that any new code pushed to the repository adheres to the clang-format configuration provided in the root folder. This was an exciting opportunity to deepen my understanding of CI/CD workflows, especially since I am actively learning about them.

The Issue

The faker-cxx repository already had a clang-format configuration file, but there was no automated process to check if submitted code adhered to it. Previously, contributors had to run clang-format locally before committing, which some contributors skipped and was also prone to human error. Automating this check would ensure consistency and reduce the chances of merging pull requests with formatting-related problems.

My Approach

To begin, I familiarized myself with clang-format and its configuration guidelines. I had previously used clang-format for contributions to this repository, but this time, I needed a more in-depth understanding to integrate it into a CI pipeline. Here’s the official release document I referred to.

Then, I explored the GitHub Actions Marketplace for pre-configured clang-format actions, hoping to find a verified and actively maintained option. Unfortunately, none met these criteria, so I decided to write the workflow from scratch.

Creating the GitHub Actions workflow involved defining steps to:

• Check out the repository.
• Install clang-format if it wasn’t already available.
• Cache dependencies to speed up the CI pipeline.
• Run clang-format on relevant files.
• Check for unformatted files and fail the CI run if any were found.

Implementing the CI Workflow

Here is the core of the GitHub Actions workflow I wrote:

jobs:
  check_formatting:
    name: Check Code Formatting
    runs-on: ubuntu-24.04

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Cache clang-format dependencies
        uses: actions/cache@v3
        with:
          path: /tmp/apt-cache
          key: clang-format-${{ runner.os }}-${{ hashFiles('**/apt-packages.txt') }}
          restore-keys: |
            clang-format-${{ runner.os }}-

      - name: Install clang-format
        run: |
          if [ ! -f /tmp/apt-cache/clang-format-18 ]; then
            sudo apt-get update
            sudo apt-get install -y clang-format-18
            touch /tmp/apt-cache/clang-format-18
          fi

      - name: Run clang-format
        run: |
          clang-format src/**/*.cpp src/**/*.h include/**/*.h -i -style=file

      - name: Check for unformatted files
        run: |
          git diff --exit-code || (echo "Code is not formatted correctly" && exit 1)

Key Features:

• Path Filters: I ensured the workflow only ran when changes were made to files relevant to the clang-format check. This optimization avoided unnecessary CI runs for unrelated updates like documentation changes.
• Caching: By caching the clang-format dependencies, I reduced the time taken for subsequent runs. This step was implemented using the actions/cache@v3 action.

Testing and Deployment

After writing the workflow, I tested it on my fork of the repository before pushing it upstream. This step was helpful to catch any issues early. Once I confirmed it was working as expected, I opened a pull request to the main repository.

ci: add clang-format #987

mayank-Pareek posted on Nov 20, 2024

This closes #953

This PR introduces a GitHub Action to check code formatting using clang-format.

Workflow

• Runs only on push and pull_request events for include/**/*.h,src/**/*.cpp and src/**/*.h files.
• Cache check for clang-format-18 to avoid re-installation if it is already installed.
• Validates formatting using git diff and fails the workflow if unformatted files are detected.

View on GitHub

The maintainer reviewed and merged the PR after a quick review, as the CI pipeline functioned smoothly and added significant value to the repository.

Reflection

Adding this CI workflow to faker-cxx helped streamline the development process by automating an otherwise manual task. The repository now has an extra layer of validation, ensuring that all incoming code adheres to the defined coding standards. This experience enhanced my knowledge of setting up CI pipelines, including caching and optimization techniques.