Contributing

Your help is essential. Our Getting Started describes the project, its purpose and caveats, and is a recommended reading for contributors.

Contributions to this project are dedicated to the public domain under this license.

Please note that this project is released with a contributor Code of Conduct and by participating in this project, you agree to abide by its terms.

How to contribute#

I want to contribute#

Legal Notice#

When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license.

Commit messages#

Code contributions are accepted via the normal GitHub pull request mechanism. Please follow our advices when crafting commit messages and those advices basically come down to this list:

• First line should be maximum 50 characters long.
• It should summarise the change and use imperative present tense.
• The rest of the commit message should come after a blank line.
• We encourage you to use Markdown syntax in the rest of the commit message.
• Preferably keep to a 72-character limit (for git log constraints) on lines in the rest of the message.

If a commit is related to a particular issue, put the issue number after a hash (#) somewhere in the detail. You can put the issue number (or JIRA reference if you know it) at the beginning of the first line summary.

Steps to follow#

To help you get your feet wet and get you familiar with common contribution processes, here is a mere diagram which shows various steps to properly contribute:

Here are the typical steps explained:

1. Sign-in

   • As a developer, you will have to sign-in into GitHub online interface using your own account.

2. Clone

   • Then you will be able to clone this repository which is holding the source code that you want to modify.

3. New Pull Request

   • After having modify the code, you can create a new GitHub Pull Request (associated to a new branch) that will hold your modifications (with one or more commits).

4. Valid?

   • This Pull Request contains the modified code and after being pushed, an automatic CI unit testing tool will be launched.

5. Review

   • The result of those tests will be shown (telling if it passes the quality checks) and a reviewer will take into account this PR in order to review it.

6. Discuss

   • An exchange between you and the reviewer can be made inside this PR where comments can be added or new code refactoring can also be pushed.

7. Merge

   • Finally, the reviewer will merge the PR and the resulting code will go to the main branch of the project.

Contribution Guidelines#

Before sending your Pull Request for review, just make sure your changes are consistent with the guidelines and coding style:

General guidelines#

• Remember to include unit tests when you contribute new features, as they help to:

  a) prove that your code works correctly (with a purpose to target which will validate a wanted feature)

  b) guard against future breaking changes to lower the maintenance cost.

• Bug fixes also generally require unit tests because the presence of bugs usually indicates insufficient test coverage.

• When you contribute a new feature, the maintenance burden is (by default) transferred to our team. This means that the benefit of the contribution must be compared against the cost of maintaining the feature. Therefore, keep in mind to integrate small feature, doing only one wanted action (i.e. not growing the project as a bloatware)

• As every PR requires several CPU hours of CI testing, we discourage submitting PRs to fix one typo, one warning, etc. We recommend fixing the same issue at the file level at least (e.g. fix all typos in a file or fix all compiler warnings in a file, etc.)

NOTE: Issues are best used as a task list, where each issue contains one and only one thing to be addressed, resolved, fixed or decided. So please include only one work item per issue. This helps us know when issues are completed and can be closed. In turn, this helps everyone watching the issues know when the item they’re interested in has been resolved.

JavaScript coding style#

The linter will help you for JavaScript syntax checking, but you can also follow this code style:

• When describing code, refer to methods, using their full name. For example, use Array.prototype.reduce() instead of reduce().
• If your code contains argument with default parameters, explain what happens if they are omitted when calling the function and what the default case is.
• If your code uses recursion, explain the base cases.
• Use variables only when needed and prefer const when values are not altered after assignment, otherwise use let (avoid var).
• Use camelCase for function and variable names if they consist of more than one word.
• Try to give meaningful names to variables. For example use letter, instead of “lt”.
• Use () if your function takes no arguments.
• Use _ if an argument inside some function (e.g. for Array.prototype.reduce() parameters) is not used anywhere in your code.
• Always use soft tabs (4 spaces indent for clarity) and never hard tabs.
• Force the declaration of curly braces (i.e. “{” and “}”) whenever possible (like after each if/else statement).
• Always use single quotes for string literals. Use ES6 template literals instead, if necessary.
• If your snippet’s code is short enough (around 128 characters as standard display ratio is now 16:9), you can make it a single-line function otherwise, use multiple lines.
• Use strict equality checking (=== and !== instead of == and !=), unless you specifically have reason not to. Prefer using the ternary operator (condition ? trueResult : falseResult) instead of if else statements whenever possible.
• Avoid too much nesting ternary operators (but you can do it if you feel like you should).
• Use dot notation object.property for object properties, when possible. Use bracket notation object[variable] when accessing object properties using a variable.
• Use ES6 arrow functions as much as possible, except when you can’t.
• Use semicolons whenever necessary. If your function’s body is a single statement, return an expression ended with a semicolon.
• Leave a single space after a comma (,) character for example in a list of values.
• Try to strike a balance between readability, brevity, and performance.
• Never use eval() for performance purpose and security.

For JavaScript’s code, an ESLint configuration file is included in the root of the project repository. This is not integrated with a git commit hook, so you need to manually make sure that all your code conforms to the style.

How to triage bugs#

You can help maintainers by examining the existing bug reports in GitHub’s projects or Issues tabs and adding instructions to reproduce them, or categorizing them with the correct labels.

For bugs that are similar to another one, use the Duplicate label.
For other bugs, use the Bug label.
Feature requests should get the Feature label.
Any speeling or documentation improvement, should get the Documentation label.
If some information is missing from the bug (e.g. you can’t reproduce it based on their instructions) add the Help wanted label.

Resources#

• Contributing to Open Source on GitHub
• Using Pull Requests on GitHub
• Online GitHub Docs

Language Requirements#

Besides the various coding standards and commit requirements, we also require both code and commits to be written in proper English language. A typo or grammar error happens and isn’t the end of the world but please double-check your spelling before committing something.

The use of offensive or otherwise negative language aimed at other projects, people, organizations and the likes is not allowed. Our code is not the place to share any sexist, racist or otherwise offensive opinions.

For more information, see our code of conduct

Legal Requirements#

All our source code is following the open-source free software development methodology and licensed under the MIT license unless stated otherwise. This means that any contribution you make must use the same license. Even if it’s compatible with the MIT license, we simply do not accept other ones (GPL, Apache, etc.). An up-to-date copy of the license can be found in a file called “license” that lives in the root directory of the repository unless specified otherwise.

The use of proprietary code or code taken from other projects or generated by using Microsoft CoPilot, without prior permission, is also strictly forbidden.