Skip to content

Latest commit

 

History

History
151 lines (100 loc) · 6.21 KB

CONTRIBUTING.md

File metadata and controls

151 lines (100 loc) · 6.21 KB
Raw

Contributing

If you would like to contribute to this project, please open an issue or a pull request. We are always looking for ways to improve the project and would love to hear your ideas.

The latest changes are always in master branch, so please make your Pull Request against that branch.


🚩 Development Requirements

Before you begin, you will need to set up your local development environment. Here is what you'll need:

→ Optional Tools

  • Pre-commit — Automates the running of git pre-commit hooks.
    • Installation: brew install pre-commit and make hooks
  • Cz-git — Commitizen adapter, that assists in formatting git commits.
    • Installation: brew install czg
  • Act — To run and test GitHub actions locally.
    • Installation: brew install act

🛠️ Makefile

This project uses a Makefile to streamline common development tasks. The Makefile includes utilities for managing Docker environments, running tests, and linting code.

Refer to the output of make help for a comprehensive list of available commands.

make help

Screenshot

💻 Workflow

Important

Please feature/fix/update... into individual PRs (not one changing everything)

  • Fork the Repository: Start by forking the repository to your GitHub account.
  • Create a Branch: In your fork, create a new branch for your work. Name it appropriately based on the feature, fix, or update you're working on.
  • Make Your Changes: Implement your changes
  • Update Documentation: If you've made changes that affect the project's documentation, ensure it is updated.
  • Run Linters: Ensure your code passes all linting checks using make lint.
  • Commit Your Changes: Use the Conventional Commits standard for your commit messages. You can use make commit to assist in creating commit messages.
  • Push Your Changes: Push your branch to your fork on GitHub.
  • Open a Pull Request: Submit a pull request to the master branch of the original repository. Ensure your PR is focused, addressing a single feature, fix, or improvement.

⚡️ Continuous Integration with GitHub Actions

Our project employs GitHub Actions for continuous integration, ensuring code quality and reliability. We encourage contributors to review our workflow configurations to understand the CI processes:


📩 Commit Message Guidelines

We follow the Conventional Commits standard. Please structure your commit messages as follows, using the appropriate prefix:

Examples:

git commit -am 'feat: some feature was introduced'
git commit -am 'fix: something has been fixed'

Allowed Prefixes:

Prefix Purpose
feat Introduces a new feature
fix Fixes a bug
perf Improves performance
docs Documentation only changes
style Code style changes (formatting, missing semi-colons, etc.)
deps Updates dependencies
refactor Code changes that neither fixes a bug nor adds a feature
ci Changes to our CI configuration files and scripts
test Adding missing tests or correcting existing tests
revert Reverts a previous commit
build Changes that affect the build system or external dependencies
chore Other changes that don't modify src or test files
security A code change that fixes a security issue

🔍 Coding Standards and Tools

We enforce coding standards to maintain high code quality and readability. Here's a list of tools we use:

→ Yaml Lint

We use yamllint to enforce coding standards in YAML files.

To lint yaml files run:

make lint-yaml

by default, cytopia/yamllint Docker image will be used to run linter.

→ Action Lint

We use actionlint to enforce coding standards in GitHub Actions workflows.

To lint GitHub Actions run:

make lint-actions

by default, rhysd/actionlint Docker image will be used to run linter.


📦 Pre-commit Hooks

Pre-commit hooks are an optional but highly recommended way to automate the linting and quality checks before committing changes to the repository. This project provides a predefined configuration that helps in maintaining code quality and consistency.

→ Configured Hooks

Our pre-commit configuration includes several hooks:

  • Trailing Whitespace: Removes unnecessary trailing spaces.
  • End-of-File Fixer: Ensures that files end with a newline.
  • Check Added Large Files: Prevents accidentally adding large files to the git repository, with a current limit set to 600 KB.
  • Commitizen: Ensures commit messages meet the conventional commit format. This hook is triggered at the commit message stage.

→ Installing Pre-commit Hooks

To utilize these hooks, you first need to install them using the command provided by the Makefile:

make hooks