<!--
SPDX-FileCopyrightText: 2023 Louis Hollingworth <louis@hollingworth.nl>

SPDX-License-Identifier: CC0-1.0
-->

# How to contribute

<!-- TODO: Change <PROJECT_NAME> -->

Contributions to Klara-Matrix are highly encouraged and desired. Below are some guidelines that will help make the process as smooth as possible.

## Getting Started

- Make sure you have a [Ludo Git account](https://git.ludoviko.ch/user/sign_up)
- Submit a new issue, assuming one does not already exist.
  - Clearly describe the issue including steps to reproduce when it is a bug.
  - Make sure you fill in the earliest version that you know has the issue.
- Fork the repository on GitHub

## Suggesting Enhancements

- When submitting an issue for an enhancement, please be as clear as possible about why you think the enhancement is needed and what the benefit of
  it would be.

## Making Changes

- From your fork of the repository, create a topic branch where work on your change will take place.
- To quickly create a topic branch based on main; `git checkout -b my_contribution main`. Please avoid working directly on the `main` branche.
- Make commits of logical units.
- Check for unnecessary whitespace with `git diff --check` before committing.
- Please follow the prevailing code conventions in the repository. Differences in style make the code harder to understand for everyone.
- Make sure you have added all the necessary unit tests for your changes.
- Run _all_ unit tests to assure nothing else was accidentally broken.
- Make sure your commit messages are in the proper format.
  - The first line of the commit message should be a short description around 50 characters in length and be prefixed with the GitHub issue it refers to with parentheses surrounding that. If the GitHub issue is #25, you should have `(#25)` prefixed to the message.
  - If the commit is about documentation, the message should be prefixed with `(doc)`.
  - If it is a trivial commit or one of formatting/spaces fixes, it should be prefixed with `(maint)`.
  - After the subject, skip one line and fill out a body if the subject line is not informative enough.
  - Sometimes you will find that even a tiny code change has a commit body that needs to be very detailed and make take more time to do than the actual change itself!
  - The body:
    - Should wrap at `72` characters.
    - Explains more fully the reason(s) for the change and contrasts with previous behavior.
    - Uses present tense. "Fix" versus "Fixed".
    - Contains a sign off statement to confirm that you agree to the [DCO](#DCO)

A good example of a commit message is as follows:

```text
(#123) Add more cowbell to Get-Something

The functionality of Get-Something would be greatly improved if there was a little
more 'pizzazz' added to it. I propose a cowbell. Adding more cowbell has been
shown in studies to both increase one's mojo, and cement one's status
as a rock legend.

Signed-off-by: Your Name <your@email.address>
```

## Documentation

We are not infallible and as such the documentation may need corrections. Please feel free to contribute changes to improve the documentation as described in the [Making Changes](#making-changes) and [Submitting Changes](#submitting-changes) sections.

## Submitting Changes

- Push your changes to a topic branch in your fork of the repository.
- Submit a pull request to the main repository.
- Once the pull request has been reviewed and accepted, it will be merged with the master branch.
- Celebrate

## DCO

```text
Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.
```

## Additional Resources

- [General GitHub documentation](https://help.github.com/)
- [GitHub forking documentation](https://guides.github.com/activities/forking/)
- [GitHub pull request documentation](https://help.github.com/send-pull-requests/)
- [GitHub Flow guide](https://guides.github.com/introduction/flow/)
- [GitHub's guide to contributing to open source projects](https://guides.github.com/activities/contributing-to-open-source/)