Skip to content

Latest commit

 

History

History
161 lines (113 loc) · 9.29 KB

CONTRIBUTING.md

File metadata and controls

161 lines (113 loc) · 9.29 KB
Raw

Contributing

First of all, thanks for contributing and making the project better!

As a contributor, we would like you to follow the following guidelines.

Using the issue tracker

The issue tracker is the channel for bug reports, features proposals and questions. Before opening an issue or a pull request, please use the GitHub issue and pull requests search to make sure the bug, feature or pull request hasn't already been reported or implemented.

Bug report

A good bug report shouldn't leave others needing to chase you for more information. Please try to be as detailed as possible in your report and fill the information requested in the Bug report template.

Feature proposal

Feature proposals are welcome, but take a moment to find out whether your idea fits in with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Please provide as much detail and context as possible and fill the information requested in the Feature proposal template.

Question

Any questions regarding this project are welcome. Please fill the information requested in the Question template.

Coding guidelines

Coding style

The coding style should be enforced through tools as much as possible. Please make sure to use editor extensions, e.g. on the VS Code marketplace, to visualise code linting on the fly. You can of course always manually run the linter with npm run lint.

  • For TypeScript code, documentation, YAML, etc. we conform to the XO code style, based off of ESLint.
  • For C/C++ code we conform to the Clang tidy code style, with Clang format for formatting the source code.

Coding rules

In order to keep the source code consistent and high quality, all source code should:

  • be easy to read and understand, ideally without requiring comments
    • use functions to simplify and structure complex code
    • simplify and/or remove code to make it more readable
    • source code should not require any documentation, if it does it is probably not simplified enough
  • use verbose variable names (e.g. referenceVoltage instead of vRef)
  • follow the Return early pattern
  • have no linting errors
  • have a test for every possible case introduced by the code change
  • result in none, or negliable, decrease in test coverage
  • have its public API documentation updated, if necessary

Documentation rules

In order to keep the documentation consistent and high quality, all documentation should:

  • refer to brands in bold with the corresponding capitalisation, e.g. GitHub, npm, Node.js
  • use links when you are referring to:
  • use single backtick code quoting for:
    • programming language keywords, e.g. function, async, string
    • commands inside sentences, e.g. the git command
    • packages or modules, e.g. the @commitlint/load module
  • use triple backtick code formatting, with corresponding language for syntax highlighting, for:
    • code examples 
      function square(value: number): number {
  return value ** 2;
}
    • sequences of commands 
      $ mkdir test
$ cd test

Commit guidelines

Please use atomic commits as much as possible. An atomic commit is a commit that follows the following rules.

  • Contain exactly one self-contained change.
  • Does not create an inconsistent state, such as build failure, test failures, linting errors, etc.

In short, all your tests need to be green on every commit and your application shouldn’t break. Every commit has a clear commit message and a description detailing what the purpose of these changes was. Lastly, the commit should only have changes pertaining to one fix or feature (or whatever you were working on). Don’t have commits where you “fixed that bug and also implemented the feature and then also refactored some class”.

Atomic commits will help you git legit

Commit message format

We use the Conventional Commits 1.0.0 specification for our commit messages. The commit message format is checked pre-commit using commitlint. The rules for the commit messages are specified in the @vidavidorra/commitlint-config rules, which modifies @commitlint/config-conventional rules.

In short, commit messages should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Where type must be one of the following types.

Type Description (used to ...)
build Change that affects the build system.
ci Change or add CI configuration fies and scripts.
chore Change something witout impacting the user (e.g. bump version).
docs Change or add documentation.
feat Add a new feature.
fix Fix a bug.
perf Improve code performance.
refactor Refactor code without changing the public API.
revert Revert a previous commit, referencing the reverted commit SHA.
style Change code style (formatting, missing semicolons, etc.).
test Add missing tests or modifying existing tests.

The body and/or footer can be used to reference issues and pull requests or close issues using the keywords listed below, originating from the GitHub documentation Using keywords in issues and pull requests.

  • closes: closes the linked issue, for example, Closes #10, Closes vidavidorra/commitlint-config#10 or Closes #10, closes #11. Note that closing multiple issues requires the full syntax for each issue.
  • refs: reference an issue or pull request, for example Refs #10, Refs withthegrid/support#10 or Refs #10, refs #11.

Examples

Simple commit message without scope.

docs: add contributing guidelines

Commit message with scope and closing an issue.

feat(Renovate): group linters

Closes #123.

Commit message with scope and breaking change.

feat(node-test)!: rename `node-version` input to `nodeVersion`, defaulting to 18

Make the `node-test` inputs consistent with all other workflows.

Closes #123, refs #111.

Versioning

We follow the Semantic Versioning 2.0.0 standard and have automated releases using semantic-release. This uses the commit messages to determine what type of release to create, so it is very important to follow the Commit message format. Regular releases are based on the main branch, where pre-releases are based on the beta branch.

Note For hardware, anything except documentation and drop-in part number changes is a breaking change as it results in different PCB fabrication files, for example Gerbers.