[ADR] Introduce Common Open-Source Tooling into Codebase to Increase Productivity and Developer Experience

[MFarabi619]

TLDR: Less potato commits, less potato PRs, less potato PR reviews, and less repetitive discussion. More vroom vroom so you can sleep in till 2 pm. Repetitive manual work bad. Robots good.

cuHacking Dev Team Now	cuHacking Dev Team Soon

Problem Statement

I'm always frustrated when I forget to run linters before committing my code, which leads to broken builds and additional work to fix errors. This reduces our team's efficiency and can introduce bugs into the codebase. Managing Git hooks manually is also error-prone and inconvenient.

Additionally, PR reviews take too much time due to syntax or code style nitpicks, which can be standardized with ESLint. The current commit messages sometimes aren't helpful and can be potentially even misleading.

We are also following a trunk-based development model. But we aren't currently versioning our platform semantically to keep track of added features and bugfixes, which trunk-based development makes really easy to do.

Goals

1. Ensure that linters are automatically run before committing code.
2. Reduce the chances of broken builds, and improve overall code quality and health.
3. Simplify the management of Git hooks to make the process less error-prone and more convenient.
4. Standardize commit messages to improve readability and enforce a consistent commit history.
5. Automate the release process to streamline deployments and versioning.

Out of Scope

• Custom scripts for Git hooks that are not managed by the proposed tools.
• Advanced configurations or integrations beyond basic pre-commit and pre-push hooks for the initial setup.

Solution Summary

History/Context

The current process of managing Git hooks manually has proven to be inefficient and error-prone. This often results in broken builds and additional work to fix errors, which reduces overall team efficiency.

As patterns emerge in the codebase and we figure out best practices, they can be enforced with tools rather than on long pages of documentation that still need be read, understood, interpreted correctly, and then implemented accordingly in the context of the problem.

The need for an automated and reliable solution led to the consideration of integrating several tools into our project.

Solution

I propose to integrate the following tools into our project:

1. Husky: Automates the running of scripts before making commits, such as linting, ensuring that code quality is maintained and reducing the chances of broken builds.
2. commitlint: Enforces a consistent commit message style by checking if commit messages meet the conventional commits specification. This helps ensure that commit messages are parsable by semantic release and are not misleading.
3. Commitizen: Facilitates the process of creating standardized commit messages, making it easier for developers to follow the commit message conventions and reducing the learning curve.
4. lint-staged: Runs linters on staged files, ensuring only code that passes linting rules is committed. This reduces the time spent on PR reviews due to syntax or code style nitpicks.
5. semantic-release: Automates the versioning and release process, ensuring that releases are consistent and based on the commit history. It parses the commit messages to generate tags and changelogs, and commitlint ensures that our commit messages are parsable by semantic release.

Other options considered

• Manual Git Hooks: Writing custom scripts and placing them in the .git/hooks directory. However, this approach is less flexible and harder to maintain across different environments and team members.
• Using only lint-staged: While useful for running linters on staged files, it does not provide the comprehensive hook management that Husky offers. Additionally, it does not address commit message standardization or automated releases.
• Manual commit message conventions: Relying on team members to manually follow commit message conventions without automated enforcement, which can lead to inconsistencies.