Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
92 lines (60 loc) · 5.5 KB

CONTRIBUTING.md

File metadata and controls

92 lines (60 loc) · 5.5 KB

How to contribute

We'd love to accept your patches and contributions to this project. There are just a few guidelines you need to follow.

Ways of contributing

Contribution does not necessarily mean committing code to the repository. We recognize different levels of contributions as shown below in increasing order of dedication.

  1. Use and test the project. Give feedback on the user experience.
  2. Suggest or prioritize new features to be developed, based on substantiated input from a DSO.
  3. Report bugs or security vulnerabilities.
  4. Fix bugs.
  5. Improve the project by developing new features.

Filing bugs, security vulnerabilities or feature requests

You can file bugs against and feature requests for the project via GitHub Issues. Read GitHub Help for more information on using GitHub Issues.

Community guidelines

This project follows the following Code of Conduct.

REUSE compliance and source code headers

All the files in the repository need to be REUSE compliant. We use the pipeline to automatically check this. If there are files which are not complying, the pipeline will fail the pull request will be blocked.

This means that every file containing source code must include copyright and license information. This includes any JS/CSS files that you might be serving out to browsers. (This is to help well-intentioned people avoid accidental copying that doesn't comply with the license.)

Apache 2.0 header:

    SPDX-FileCopyrightText: Copyright Contributors to the <YOUR PROJECT NAME> project <YOUR_PROJECT_EMAIL_ADRESS@alliander.com>
    SPDX-License-Identifier: Apache-2.0

Git branching

As this project is not intended for production usage, it applies a simple main/feature model for branching for minimal overhead. New features are developed in a feature branch and directly merged back into main.

Signing the Developer Certificate of Origin (DCO)

This project uses a Developer Certificate of Origin (DCO) to ensure that each commit was written by the author or that the author has the appropriate rights necessary to contribute the change. Specifically, we use Developer Certificate of Origin, Version 1.1, which is the same mechanism that the Linux® Kernel and many other communities use to manage code contributions. The DCO is considered one of the simplest tools for sign-offs from contributors as the representations are meant to be easy to read and indicating signoff is done as a part of the commit message.

This means that each commit must include a DCO which looks like this:

Signed-off-by: Joe Smith <joe.smith@email.com>

The project requires that the name used is your real name and the e-mail used is your real e-mail. Neither anonymous contributors nor those utilizing pseudonyms will be accepted.

There are other great tools out there to manage DCO signoffs for developers to make it much easier to do signoffs:

  • Git makes it easy to add this line to your commit messages. Make sure the user.name and user.email are set in your git configs. Use -s or --signoff to add the Signed-off-by line to the end of the commit message.
  • GitHub UI automatic signoff capabilities for adding the signoff automatically to commits made with the GitHub browser UI. This one can only be activated by the GitHub org or repo admin.
  • GitHub UI automatic signoff capabilities via custom plugin for adding the signoff automatically to commits made with the GitHub browser UI.
  • Additionally, it is possible to use shell scripting to automatically apply the sign-off. For an example for bash to be put into a .bashrc file, see here.
  • Alternatively, you can add prepare-commit-msg hook in .git/hooks directory. See an example.

Code reviews

All patches and contributions, including patches and contributions by project members, require review by one of the maintainers of the project. We use GitHub pull requests for this purpose. See GitHub Help for more information on using pull requests.

Pull request process

Contributions should be submitted as GitHub pull requests. See Creating a pull request if you're unfamiliar with this concept.

Follow this process for a code change and pull request:

  1. Fork the repository.
  2. Make your change in a feature/description_of_your_change branch.
  3. Run the tests.
  4. Run the pre-commit hooks to check for code style and other issues.
  5. Submit a pull request.
  6. Pull requests will be reviewed by one of the maintainers who may discuss, offer constructive feedback, request changes, or approve the work.
  7. Upon receiving the sign-off from one of the maintainers will merge it for you.

Attribution

This CONTRIBUTING.md is adapted from Google, available at https://github.com/google/new-project/blob/master/docs/contributing.md.