Skip to content

Rules / Guidelines⚓︎

Issues⚓︎

Follow these rules for project issues:

  • An Issue should be created for every task that needs to be done.
  • Issue titles should be concise.
  • Issues should have labels if needed.
  • Issues without body/description are acceptable if the task is small and can be described with a concise title. However, it's recommended to create a detailed issue.
  • Big issues should be identified and broken into smaller plausible pieces allowing merges of related pull requests into the codebase piece by piece without breaking anything.
  • Follow the issue template of the repository for creating detailed issues. Refer to this repo for examples of issue templates.
  • Issues should contain single or multiple screenshots if applicable. Example: A frontend issue with a screenshot of the UI.
  • Issues should contain code snippets or logs if applicable. Example: A backend issue with a log of the error or a code snippet that might be causing the error.
  • Issues should be placed in the correct pipeline at all times (e.g. Icebox, In Progress, Needs Review, etc). Example: If you are working on an issue, move it to the In Progress pipeline.
  • You shouldn't assign yourself to an issue if you won't be working on it for some time. Doing so allows other team members to pick up the issue and work on it if they want.

Pull Requests⚓︎

Follow these rules for project's pull requests:

  • Pull requests titles should be concise and self-explanatory.
  • Pull requests should have labels if needed.
  • Pull requests should have a detailed description of the code changes with screenshots and/or code snippets if applicable. Try to answer the following questions:
    • What was changed?
    • Why was it changed?
    • How was it changed?
  • Pull requests containing HACKS, WORKAROUNDS or HOTFIXES are not encouraged, however, if you HAVE to do it for a good reason, provide a detailed explanation of the change and potential bugs it might cause.
  • Conversations related to pull requests should be in the done in pull request comments or GitHub Discussions rather than slack or any other platform to keep it organized and avoid losing the conversation.
  • Pull requests should be kept small and focused on the issue/ticket that is being addressed.
  • Pull requests shouldn't have more than 300 line changes.
  • Think of Single Responsibility Principle when creating pull requests. The pull request should focus on only one thing.
  • Like issues, pull requests should be broken into smaller ones when possible.
  • Big Diffs = Probably Problematic Pull request. Big pull request makes it hard to review code and find bugs.
  • Every successful merge of a pull request to main / master branch should bump version number following semver guidelines. Example: Before merge: 1.1.3 → After minor change merge: 1.2.0

Code Reviews⚓︎

  • First hour in the morning should be spent doing code reviews.
  • Code reviews should provide constructive feedback with pull request comments.

Branches⚓︎

  • We recommend the following convention for naming branches:

    <feat | fix>/<issue_number>-some-info

Example:
- feat/234-delete-order
- fix/111-broken-button

Commits⚓︎

Commit Rules:

  • ALL COMMIT MESSAGES SHOULD FOLLOW CONVENTIONAL COMMIT GUIDELINES.

    Why conventional commit guidelines?
    • Automatically generate changelogs for your project.
    • Automatically identify a semantic version bump which can be used for tagging and auto releases.
    • Much more
    Types
    Type Description
    feat A new feature
    fix A bug fix
    docs Docume­ntation only changes
    style Changes that do not affect the meaning of the code (white­-space, format­ting, missing semi-c­olons, etc)
    refactor A code change that neither fixes a bug nor adds a feature
    perf Improv­ements A code change that improves perfor­mance
    test Adding missing tests or correcting existing tests
    ci Changes to our CI config­uration files and scripts (example scopes: Travis, Circle, Browse­rStack, SauceLabs)
    chore Other changes that don't modify src or test files
    revert Reverts a previous commit
    Quick Examples
    • feat: new feature
    • fix(scope): bug in scope
    • feat!: breaking change / feat(scope)!: rework API
    • chore(deps): update dependencies

  • Commit messages should be clear and meaningful.

    Why is this important?

    A well-written commit message is the best way to communicate context about a change to other developers working on that project, and indeed, to your future self. Furthermore, understanding the change made by a commit message makes development and collaboration more efficient.

  • It is preferred to write commit messages in present tense. Example: feat: add Button.vue instead of feat: added Button.vue. Read more...

  • Do not end commit messages with a period.

Testing⚓︎

  • Write and maintain tests for any code changes.
  • Each push to main / master branch should improve coverage.
  • Pull requests decreasing test coverage shouldn't be merged!
  • Follow Test-driven Development if possible.

Versioning⚓︎

  • Use semantic versioning.

    Tldr 
    MAJOR.MINOR.PATCH

  • Releases should be named in the format vX.Y.Z.

References⚓︎