Skip to content

Contributing guidelines

Our goal is to make kernl development smooth, stable and open. We can't do this without our user community! Please read this document before contributing!

Code of Conduct

Kernl has adopted the Contributor Covenant as its Code of Conduct, and we expect project participants to adhere to it. Please read the full text so that you can understand what actions will and will not be tolerated.

Open Development

Kernl uses GitHub as a source of truth. The core team works directly on it. All changes are public.

Writing and formatting text

In a global way, texts in Issues, PRs and commits should be written in English, with care, consistency, and clarity. Use (Markdown) to structure your texts, and to make them more readable.

Development Process

Ask a question / share your ideas or new features

If you have a question, an idea for a new feature, or an optimization, you can use the dedicated discussion forum.

Issues

Before submitting an Issue, check the issue tracker to see if a similar version is already present

Bugs

If you think you've found a bug but don't have the time to send a PR, please:

Bug reports without a reproduction will be immediately closed.

tips for writing your Issue

  • Give a concise and explicit title to the problem so that you can quickly understand what it is about.
  • Describe the problem clearly and in detail. Explain what is not working as expected, what you expected to happen and what happened instead. Include as much information as possible, all the steps you need to take to reproduce the bug, etc. If you have ideas on how to fix the problem, feel free to include them in your description.

Feature requests

If you would like to request a new feature or an enhancement, but are not planning to open a Pull Request, you can open a dedicated issue. You can also use the discussion forum for feature requests that you would like to discuss.

Proposals

If you intend to make non-trivial changes to existing implementations, we recommend that you file an Issue with the proposal template. This allows us to reach agreement on your proposal before you put any effort into it.

Documentation

If you would like to add or improve documentation or tutorials, but are not planning to open a Pull Request, you can open a dedicated issue. You can also use the discussion forum to discuss this topic.

Development

Branch Organization

Kernl works with a main branch. This is the source of truth.

Each new Pull Request, for a new feature, bug fix, or other, must be done on a new branch.

Standardization of branch names

The name of a new branch must respect the following format: 

<type>(scope)/<subject>

Which types and characters are allowed?

The types of new branches are inspired by the values of Conventional commit.

List of possible types:

  • feat: new functionality, optimization or implementation of a proposal.
  • fix: bug fix.
  • docs: addition or modification of the documentation.
  • refactor: a change in the code that does not result in any difference in behavior.
  • test: adding tests, refactoring tests. No production code change.
  • chore: upgrading dependencies, releasing new versions. Tasks that are regularly done for maintenance purposes.
  • misc: anything else that doesn't change production code, yet is not test or chore. e.g. updating GitHub actions workflow.

Allowed characters for the subject: 

[a-z_-]

Examples

  • feat/debugger
  • feat/backward_layernorm
  • refactor/refactor-kernels
  • docs/contribution-guide

Installation

You will find the installation, start-up, testing and formatting procedures on the dedicated page.

Pull Requests

You want to contribute by opening a Pull Request, we appreciate it. We'll do our best to work with you and get the PR reviewed.

If you're working on your first Pull Request, you can learn how from this free video series from Kent C. Dodds "How to Contribute to an Open Source Project on GitHub" and "About pull requests".

Recommendations

  • Any new Pull Request must be created from the main branch.
  • The name of the new branch must follow the standardization
  • A PR should be kept as small as possible. Smaller PRs are much easier to examine and merge.
  • Make sure the PR only does one thing, otherwise split it up.
  • Write a descriptive title. It is recommended to follow this commit message style.
  • The description should be clear and structured to improve readability.
  • When relevant, remember to reference the issue with fix #issue_number.
  • Finally, while your PR is in progress, leave it as a draft. Once finalized, make it ready for review.

contribution is more important than following any procedure

The maintainers will review your code and point out obvious problems. Your contribution is more important than following any procedure, although following these recommendations will certainly save everyone time.

Breaking Changes

When adding a new Breaking change, we recommend following this template in your Pull Request description:

### Breaking change

- **Who does this affect**:
- **How to migrate**:
- **An index to measure the severity and effort required for migration**:

Semantic Commit Messages

Commit messages must respect the Conventional commit specification.

The principle is simple, the commit must respect the format: 

<type>(<scope>): <subject>

The types are described in the specification, the message must be lower case.

Please pay special attention to the breaking changes

A breaking change MUST be indicated by a ! immediately before the :.

Example

fix!: fake commit message.