Skip to content

Latest commit

 

History

History
142 lines (97 loc) · 6.19 KB

CONTRIBUTING.adoc

File metadata and controls

142 lines (97 loc) · 6.19 KB

Contributing

Table of Contents

Welcome! We are excited that you are interested in contributing to our project! However, there are some things you might need to know, so please browse the following:

Ways to Contribute

There are multiple ways of getting involved:

As a new contributor, you are in an excellent position to give us feedback to our project. For example, you could:

  • Fix or report a bug.

  • Suggest enhancements to code, tests and documentation.

  • Report/fix problems found during installing or developer environments.

  • Add suggestions for something else that is missing.

Community Guideline

Be nice and respectful to each other.

File an Issue

Please check briefly if there already exists an Issue with your topic. If so, you can just add a comment to that with your information instead of creating a new Issue.

Report a bug

Reporting bugs is a good and easy way to contribute.

To do this, open an Issue that summarizes the bug and set the label to "bug".

Suggest a feature

To request a new feature you should and summarize the desired functionality and its use case. Set the Issue label to "feature" or "enhancement".

Contribute Code, Documentation and more

You want to contribute code, documentation or 'your fantastic thing x'. Great, however, there are some practical points to check to make sure that everything runs as smoothly as possible.

  • It is always best to discuss your plans beforehand, to ensure that your contribution is in line with the project goals.

  • Check the list of open Issues. Either assign an existing issue to yourself, or create a new one that you would like to work on, and discuss your ideas and use cases.

  • Follow the project convention and style regarding test, code and documentation, commit style etc.

  • The project can decide to decline a contribution not following the general project guidelines, or deemed to not fit into the general project goal/architecture.

  • Make sure you have an understanding of the Pull Request Lifecycle

  • You agree to that in general, all contributions to this project will be released under the inbound=outbound norm, that is, contributions are submitted under the same terms as the project licenses. In a more formal way - 'Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of the projects License, without any additional terms or conditions.'

  • Sign your commits.

Pull Request Lifecycle

Generally speaking, you should fork this repository, make changes in your own fork, and then submit a pull-request. This workflow is common, maybe even expected if nothing else mentioned, and is called the Fork-and-Pull model

A practical example of such a workflow could be:

  1. Fork the repository.

  2. Create a topic branch from your fork main branch, i.e. myfeaturebranch

  3. Push your changes to the topic branch (in your fork) of the repository, i.e myfeaturebranch.

  4. Open a new pull request to main project.

  5. Project maintainers might comment and give feedback on your Pull Request.

Commit Guideline

DCO - Signoff and Signing a Commit

Note
 Signoff and signing: Two similar terms for two different things
A Signoff assures to the project that you have the right to contribute your content
A Sign assures that the commit came from you

Signoff (DCO agree)

A standard practice in the Open Source communities is the DCO - Developer Certificate of Origin. DCO a lightweight way for a project to assure that the contributor wrote and/or have the right to submit the contribution.

It is supersimple!

As part of filing a pull request you agree to the DCO - by just adding a sign off to your commit. Technically, this is done by supplying the -s/--signoff flag to your Git commits:

Example:

$ git commit --signoff -m 'fix: add fix for superbug x'

Sign

You can also sign the commit with -S/--gpg-sign. Besides extra trust, it also gives your commit a nice verified button in the UI on most Git platforms and further assures trust.

Older versions of Git requires that you have a GPG keypair set up, see Sign commit on GitHub with GPG key. For newer versions you can use SSH for signing Sign commit on GitHub with SSH key.

`$ git commit --signoff --gpg-sign -m "fix: add fix for the bug"`

Commit Standard

Aim for a clear human readable commit history:

  • First - does the project have a defined commit message practice, please follow that.

  • Make sure you Sign-Off your commits.

  • In general

    • If the project does not have standard for commits, you might want to consider Conventional Commit standard.

    • Group relevant changes in commits, avoid scope creep and keep focus on the relevant issue.

    • Your commit messages should tell a human reader what will it do when the commit is applied.

    • Make your commit message/s easily human readable in a expected way:

      • A Conventional Commit example:
        fix: add a null pointer check to MyMethod parameter
        Would be read as 'When this fix is applied it will add a null pointer check to MyMethod parameter'

Reporting security issues

If you discover a security issue, please bring it to our attention.

Security reports are greatly appreciated.

Development Guidelines

For a guide on how to get started with Development, see the DEVELOPMENT Guide.

Happy contributing!