Ensuring a Clean, Reliable, and Developer-Friendly Codebase

[AliceR]

Maintaining high code quality and consistency is crucial for the long-term success and maintainability of our open-source project. Adhering to a unified code style, implementing automated checks, and enforcing quality gates will help improve developer productivity, reduce bugs, and foster collaboration within the community.

Currently, there might be inconsistencies in how code is formatted, linted, or tested, which can lead to:

• Code review overhead due to unnecessary formatting or style issues.
• Potential introduction of errors if testing or linting is not consistently applied.
• Reduced contributor experience due to unclear or varying standards.

To address these issues, we propose implementing structured practices to automate and enforce code quality.

Proposed Solution

Step 1: Enable Format-on-Save in Local Development Environments
Developers should configure their IDEs or text editors to automatically format code on save.
This ensures code is consistently styled as per project standards before it even reaches version control.
We can provide clear documentation in our repository on how to configure format-on-save for common editors (I think most of us use VS Code?).

Step 2: Implement Git Hooks to Run Quality Checks
We do have husky installed to the project, but the pre-commit hook is not running for me, at least. I need to investigate, and make sure it works for other new contributors as well!

Use Husky to set up pre-commit hooks that:

• Automatically format code.
• Run linters to catch syntax or style issues.
  This ensures that no code can be committed unless it meets the project's standards.

Additionally, we could set up a pre-push hook to:

• Execute unit and end to end tests to catch issues early.

Step 3: Enforce Quality Gates in CI/GitHub Actions
Configure GitHub Actions (or any other CI tool) to run checks for formatting, linting, and tests.
We should the CI pipeline to fail and block merges for any violations.
This guarantees that only high-quality code reaches the main branch.

Benefits

Consistent codebase: Code will always adhere to the project's style and standards.
Improved productivity and collaboration: Reduces time spent on manual corrections during code reviews, and less time discussing style issues.
Early detection of issues: Bugs and inconsistencies are caught before they reach production.
Contributor-friendly: Provides a clear and automated way for developers to meet standards.

---

Action Items

• Document format-on-save setup for popular editors in the repository's CONTRIBUTING.md. chore: Update SETUP.md to include part about format on save #1306
• Investigate and potentially fix our git hooks for formatting, linting, and testing using Husky. chore: review commit hooks #1345
• Investigate and potentially update CI/GitHub Actions to enforce quality checks and block non-compliant PRs.

cc @hanbyul-here as per our conversation for visibility and input.

Looking forward to feedback and collaboration on implementing these practices!

[hanbyul-here]

Thanks for writing the thoughts down 🙇 I am tempted to add some GitFlow practice here that aligns with conventional commits, but I think it is better to leave this ticket to be scoped clean as it is and separate Git practice.

Regarding steps 1 and 2: Maybe we can run a poll on Slack to understand everyone's setup and check if the pre-commit hook is working for everyone. @stephenkilbourn - since you helped with the initial setup, do you have any idea why the pre-commit hook might not work for some developers? For me, the pre-commit hooks work most of the time, although I occasionally notice they don't run without any specific flag.

Regarding Step 3: We have lint, typescript, and tests in place and you will get notified that any of these fail. Do you see any more improvement than what we have now? Attaching a screenshot with a list of actions that run on PR.