Trench Project / Project Guidelines

This document outlines the guidelines for the project, and how to work on it.

1. Steps to make a change

  1. Head to the project’s YouTrack board and find a task that you want to work on, or create a new one.

  2. Create a new branch with the name following the Branch Name Guidelines.

  3. Make your changes on that branch. Name your commits following the Commit Message Guidelines. Your first commit on that branch should include "In Progress", and your last commit "To Verify" at the end of the message.

  4. Create a pull request and give an extensive description of what you did. Ping Filip, Emil or whoever else you think should take a look at the PR to review it on Discord, or just ping @everyone.

  5. If any changes are requested, make them and push them to the branch, then repeat step 4.

  6. Once the PR is approved, merge it into the main branch, delete the branch and move the task to "Done" in YouTrack. Do not forget to update the documentation if necessary.

For small changes, these steps could be omitted, however it is best practice to follow them as closely as possible, and the Commit Message Guidelines should always be followed.

2. Commit Message Guidelines

The commit messages generally follow the Conventional Commits specification, however with the first letter being capitalized, the message being in the past tense and YouTrack issue ID being included at the end the message.

New features may look for example like this:

feat: Added navbar #trench-7 To Verify
The types are

  • feat for new features

  • fix for bug fixes

  • docs for documentation changes

  • style for changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)

  • refactor for code refactoring

  • perf for performance improvements

  • test for adding missing tests or correcting existing tests

  • chore for changes to the build process or auxiliary tools and libraries such as documentation generation

The hash (in this case #trench-7) is the YouTrack issue ID.

Afterwards, you can optionally specify where to move the task to, which would be Open, In Progress, To Verify, or Done.

Multiple changes in a single commit should be seperated by commas, however it is best practice to keep commits as small and as frequent as possible.

3. Branch Name Guidelines

The branch names follow a similar pattern to the commit messages, however without special characters. Starting with the Youtrack ID and the type of the task seperated by an underscore, the short description is preceeded by another underscore, the words being separated by hyphens and the tense being in the present.

For example, a branch name could look like this:

trench-2_feat_add-navbar