Skip to content

Latest commit

 

History

History
158 lines (113 loc) · 8.43 KB

CONTRIBUTING.md

File metadata and controls

158 lines (113 loc) · 8.43 KB
Raw

How to Contribute

We'd love to accept contributions to this project in any forms. You do not need to be a programming or power system expert to make a contribution. There are just a few small guidelines you need to follow before making a change.

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. Test and use the library. Give feedback on the user experience or suggest new features.
  2. Validate the model against other existing libraries. Provide validation test cases.
  3. Report bugs.
  4. Improve the Python interface or helper functions.
  5. Contributing to the C++ core
    1. Develop new mathematical algorithms
    2. Improve or add new features into the C++ codebase

A good place to start is to look at issues with the good first issue label, or to check the Power Grid Model project.

Filing bugs and change requests

You can file bugs against and change request for the project via GitHub issues. Consult GitHub Help for more information on using GitHub issues.

Community Guidelines

This project follows the following Code of Conduct.

Style Guide

For both C++ and Python code we use the pipeline to automatically check the formatting. We use black to check Python code and clang-format to check C++ code. If the code format is not complying, the pipeline will fail the pull request will be blocked.

Python

This project uses the PEP 8 Style Guide for Python Code. For all details about the various conventions please refer to:

PEP 8

Tip: Use black to automatically format your Python code to conform to the PEP 8 style guide.

Furthermore, the following conventions apply:

  • Maximum line length: 120 characters
  • Double quotes for strings, keys etc.
    • Except when double quotes in the middle of a string are required.

C++

This project follows LLVM coding standards for formatting the C++ code.

Tip: Use clang-format to format your C++ code.

pre-commit hooks

This project uses pre-commit to run a list of checks (and perform some automatic corrections) to your code (style) before each commit. It is up to the developer to choose whether you would like to use this tool or not. The goal is to make sure that each commit will pass the quality checks in the github actions workflow. Currently, these hooks are defined in {{ ".pre-commit-config.yaml".format(gh_link_head_blob) }}:

  • reuse: check if all licence headers and files are in place
  • isort: group and sort import statements
  • black: check and correct code style in a very strict manner
  • mypy: checks type hinting and data types in general (static type checker)
  • pylint: check code style and comments
  • pytest: run all unit tests

You can manually run pre-commit whenever you like:

pre-commit run

Or you can install it as a git pre-commit hook. In this case a commit will be aborted whenever one of the hooks fail.

pre-commit install

As using the pre-commit tool is not mandatory, you can always skip the tool:

git commit ... --no-verify

REUSE Compliance

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 and the pull request will be blocked.

Git branching

This project uses the GitHub flow Workflow and branching model. The main branch always contains the latest release. New feature/fix branches are branched from main. When a feature/fix is finished it is merged back into main via a Pull Request.

In case of major version release with new features and/or breaking changes, we might temporarily create a release/ branch to hold all the changes until they are merged into main.

Signing the Developer Certificate of Origin (DCO)

This project utilize 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 utilize 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 <[email protected]>

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. For an example, see here.

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. Consult the pull request process below and the 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.

The process for a code change and pull request you should follow:

  1. Create a topic branch in your local repository, following the naming format "feature/###" or "fix/###". For more information see the Git branching guideline.
  2. Make changes, compile, and test thoroughly. Ensure any install or build dependencies are removed before the end of the layer when doing a build. Code style should match existing style and conventions, and changes should be focused on the topic the pull request will be addressed. For more information see the style guide.
  3. Push commits to your fork.
  4. Create a Github pull request from your topic branch.
  5. Pull requests will be reviewed by one of the maintainers who may discuss, offer constructive feedback, request changes, or approve the work. For more information see the Code review guideline.
  6. Upon receiving the sign-off of one of the maintainers you may merge your changes, or if you do not have permission to do that, you may request a maintainer to 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