Contributions

We welcome contributions from everyone! This document will guide you through the process of making your first contribution.

Table of Contents

Initial setup

  1. Clone the repository to your own machine
  2. Check out the main branch
  3. Set up the project locally
  4. Install composer and node dependencies
  5. Ensure you can run the project

Contributing

  1. Pick a ticket from JIRA or Easy Red Mine
  2. Create a new branch from main (see below)
  3. Make your changes:
    1. Code according to our style guidelines (see below).
    2. Commit your changes: Use conventional commits (see below)
    3. Create a PR and assign it to someone for code review

Conventions used

This project uses conventional commits. This ensures git history is clean and readable.

Branches

Branches must be named in the following format:

<type>/<prefix>-<ticket_number>-<description>

Where the prefix can be either PRJ (for JIRA tickets) or ERM (for Easy RedMine tickets).

examples:

  • feature/PRJ-1234-my-new-feature
  • fix/ERM-1234-fix-user-auth
  • chore/PRJ-1234-update-ci-config

This will allow us to find the corresponding branches easily within JIRA or ERM.

Commits and commit messages

Commit Size: Aim for small, focused commits that address a single issue or feature Commit Messages: Follow the Conventional Commits specification

We use Conventional Commits to maintain a clear and informative commit history. This helps us automate changelog generation, versioning, and other project management tasks.

Commit Message Format

Each commit message should adhere to the following format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
  • type: The type of change (e.g., feat, fix, chore, docs, etc.).
  • scope (optional): The scope of the change (e.g., the component or module affected).
  • description: A brief description of the change.
  • body (optional): A more detailed explanation of the change, if necessary.
  • footer(s) (optional): Additional information like breaking changes or issue references (e.g., "BREAKING CHANGE: ..." or "Fixes #123").

Examples

  • feat: add user authentication
  • fix(auth): correct password validation error
  • chore: update dependencies
  • docs: improve installation instructions

Commitlint will automatically append the ticket Id to the commit message footer. This way you can focus on the title and optionally the body.

Tools We Use

  • We use Husky to manage Git hooks. This helps us enforce code quality and commit message standards.
  • We use Commitlint to ensure that all commit messages follow the Conventional Commits specification.
  • We use a pull request template to ensure consistent and informative pull requests.

Required Visual Studio Code Extensions

To maintain consistency and enhance productivity, we require the following Visual Studio Code extensions:

These extensions are listed in the .vscode/extensions.json file in the project root directory. Install them before starting development to ensure a smooth workflow and adherence to our coding standards.

These extensions provide essential features like linting, formatting, and code analysis that help us maintain code quality and consistency

Required PHPStorm extensions

Optional PHPStorm extensions

Code Quality with SonarQube

We use SonarQube to analyze our code for potential bugs, vulnerabilities, and code smells. This ensures that our codebase is maintainable and of high quality.

Before merging any pull request, please make sure that the SonarQube check has passed successfully. If any issues are raised by SonarQube, address them before requesting a review.

Table of Contents