# Contributing to KeyBoxen
Thank you for your interest in contributing to this project! ❤ We are excited about your
participation! Please have a look at this document to learn how to contribute to this project.
These guidelines are meant to help improve the development experience for contributors and
maintainers. We look forward to working with you on making the world a bit more pleasant by
improving KeyBoxen! 🎉
[docs]: https://git.sr.ht/~gokuldas/KeyBoxen
[maillist]: https://lists.sr.ht/~gokuldas/projects
[tracker]: https://todo.sr.ht/~gokuldas/KeyBoxen
[progress]: https://todo.sr.ht/~gokuldas/KeyBoxen/4
[copying]: COPYING
[org.fd.ss]: https://specifications.freedesktop.org/secret-service/latest/
[patches]:
## Table of Contents
- [How Can I Contribute?](#how-can-i-contribute)
- [I Have a Question](#i-have-a-question)
- [Reporting Bugs](#reporting-bugs)
- [Before Submitting a Bug Report](#before-submitting-bug-report)
- [How Do I Submit a Good Bug Report](#how-do-i-submit-a-good-bug-report)
- [Suggesting Enhancements](#suggesting-enhancements)
- [Before Submitting an Enhancement](#before-submitting-an-enhancement)
- [How Do I Submit a Good Enhancement Suggestion?](#how-do-i-submit-a-good-enhancement-suggestion)
- [Contributing Changes](#contributing-changes)
- [Before Starting the Work](#before-starting-the-work)
- [Coding Style](#coding-style)
- [Signing-off the Work](#signing-off-the-work)
- [Commit Standards](#commit-standards)
- [Commit Messages](#commit-messages)
- [Communicating the Changes](#communicating-the-changes)
## How Can I Contribute?
All types of contributions are encouraged and valued. There is more than just the programming code
that needs attention in this project. Here is non-exhaustive list of those tasks:
- Code development and bugfixing
- Application testing and bug reporting
- Database design
- Audit of cryptography and security
- Documentation
- Website
- CI/CD
- Packaging for distribution
And if you like the project, but just don't have time to contribute, that's fine. There are other
easy ways to support the project and show your appreciation, which we would also be very happy
about:
- Write/post about it
- Refer this project in your project's readme
- Mention the project at local meetups and tell your friends/colleagues
## I Have a Question
Before you ask a question, it is best to search for existing [documentation][docs], [tasks][tracker]
and [mails][maillist] that might help you. In case you have found a suitable issue and still need
clarification, you can mail us in the email thread. It is also advisable to search the internet for
answers first.
If you then still feel the need to ask a question and need clarification, we recommend the following:
- Start an new email thread in the [mailing list][maillist].
- Provide as much context as you can about what you're running into.
- Provide project and platform versions, depending on what seems relevant.
We will then take care of the issue as soon as possible.
Use a subject line like the following when you are starting a new email thread:
```
KeyBoxen: How do you do Task-A?
```
## Reporting Bugs
### Before Submitting a Bug Report
A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we
ask you to investigate carefully, collect information and describe the issue in detail in your
report. Please complete the following steps in advance to help us fix any potential bug as fast as
possible.
- Make sure that you are using the latest version.
- Determine if your bug is really a bug and not an error on your side e.g. using incompatible
environment components/versions (Make sure that you have read the [documentation][docs]. If you are
looking for support, you might want to check [this section](#i-have-a-question)).
- To see if other users have experienced (and potentially already solved) the same issue you are
having, check if there is not already a bug report existing for your bug or error in the [task
tracker][tracker] and [mailing list][maillist].
- Also make sure to search the internet (including Stack Overflow) to see if users outside of the
GitHub community have discussed the issue.
- Collect information about the bug:
- Stack trace (Traceback)
- Platform and Version (Distro, x86, ARM)
- Version of the compiler toolchain
- Possibly your input and the output
- Can you reliably reproduce the issue? And can you also reproduce it with older versions?
### How Do I Submit a Good Bug Report?
> You must **never report security related issues, vulnerabilities or bugs including sensitive
> information** to the mailing list, or elsewhere in public. Instead sensitive bugs must be sent by
> email to <dev+keyboxen@gokuldas.space>. It's adviced to encrypt the message using PGP using
> [Gokul's public key](https://meta.sr.ht/~gokuldas.pgp).
We use [a mailing list on sourcehut][maillist] track bugs and errors. If you run into an issue with
the project:
- Send us an email on the mailing list, starting the subject line with `KeyBoxen: `
- Explain the behavior you would expect and the actual behavior.
- Please provide as much context as possible and describe the *reproduction steps* that someone else
can follow to recreate the issue on their own. This usually includes your code. For good bug
reports you should isolate the problem and create a reduced test case.
- Provide the information you collected in the previous section.
Once it's filed:
1. There may be a discussion on the mailing list thread to confirm the bug.
- A team member will try to reproduce the issue with your provided steps. If there are no
reproduction steps or no obvious way to reproduce the issue, the issue will not be addressed
until they are reproduced.
2. Upon confirmation, a task will be filed on the [task tracker][tracker].
3. The task be tagged with a 'bugfix', a priority tag and possibly other tags.
4. The issue will be left to be [implemented by someone](#contributing-changes).
**NOTE:** Only confirmed bugs are entered in the tracker. The tracker is accessible only to the
maintainers of the project. Use the mailing list as your interface with the developers.
## Suggesting Enhancements
This section guides you through submitting an enhancement suggestion for KeyBoxen, **including
completely new features and minor improvements to existing functionality**. Following these
guidelines will help maintainers and the community to understand your suggestion and find related
suggestions.
### Before Submitting an Enhancement
- Make sure that you are using the latest version.
- Read the [documentation][docs] carefully and find out if the functionality is already covered,
maybe by an individual configuration.
- Perform a search on the [mailing list][maillist] and [task tracker][tracker] to see if the
enhancement has already been suggested. If it has, add a comment to the existing issue instead of
opening a new one.
- Find out whether your idea fits with the scope and aims of the project. It's up to you to make a
strong case to convince the project's developers of the merits of this feature. If your
requirements are out of the scope of the project or contrary to the projects design goals, then
consider maintaining a fork with your enhancements.
### How Do I Submit a Good Enhancement Suggestion?
1. When submitting an enhancement suggestion, consider explaining the following:
- A step-by-step description of the suggested enhancement with as many details as possible.
- Use-cases of the enhancement.
- Advantages of the new behaviour against current behavior.
- Mockup of the interaction if any is involved.
- How the enhancement improves the project for a majority of the users.
- How it fits within the design goals of the project.
2. Submit your enhancement suggestions to the [mailing list][maillist].
- Start the subject line with `KeyBoxen Feature Request: `.
3. Upon approval, the suggestion will be entered to [tasks tracker][tracker].
4. Appropriate tags will be added to the task.
5. The issue will be left to be [implemented by someone](#contributing-changes).
**NOTE:** Only confirmed feature requests are entered in the tracker. The tracker is accessible only
to the maintainers of the project. Use the mailing list as your interface with the developers.
## Contributing Changes
### Before Starting the Work
Before starting the work:
1. Ensure that nobody else has started working on the same task.
- This can be confirmed from the [task tracker][tracker].
2. Get the task entered in the tracker by a maintainer (if it hasn't already been added).
3. Get a maintainer to assign the task to you.
4. It's a good idea to occassionally update the tracker with status of your progress.
**NOTE:** Only confirmed work is entered in the tracker. The tracker is accessible only to the
maintainers of the project. Use the mailing list as your interface with the developers. Comments in
the tracker will be open for you to update.
### Coding Style
Please follow the following coding/formatting style to ensure that there is minimal friction while
using git and other coding tools:
1. Use the default Rust formatting guidline for Rust code.
- You can use `cargo fmt` (or `rustfmt`) for the purpose.
- Make sure you run this tool before every commit.
2. Use a maximum line length for 100 for markdown files.
### Signing-off the Work
Make sure to sign off each of your commits as shown below:
```sh
git commit -s
# or
git commit --signoff
```
You can also automate this process by running the following command in the local repository:
```sh
git config format.signOff yes
```
With this, you're legally agreeing to the Developer Certificate of Origin. Please see the
[website](https://developercertificate.org/) for more details. In short, you're certifying the
following to the users of KeyBoxen:
1. That you have the rights to make this contribution
2. That the contribution will remain available to the users in perpetuity under the license that the
contribution was made under.
**NOTE:** The copyright of the contribution remains with you. You are allowed to do anything that's
legal with it, except for withdrawing the contribution from the codebase.
### Commit Standards
> **NOTE:** The project is still in early phases and under heavy development. It's hard to maintain
> the required commit quality due to the fast pace of code evolution. This may be disregarded for
> the time being, until the project enters a stable and usable phase. Until then, the master branch
> commits are allowed to break build.
> **NOTE:** If you are a beginner in the use of git tool, **feel free to seek assistance of the
> maintainers** to achieve the standards mentioned below. This also applies to any other difficulties
> with git or other tools. Don't let the complexity of tooling stop you from contributing. We're
> happy to help you contribute and become a full-fledged contributor.
Each commit on the master branch is expected to meet the following requirements:
1. Fully buildable without failure
2. Contain a complete feature
This may be difficult to achieve with your preferred commit workflow. So it's advised to create a
feature branch and follow the commit workflow of your choice. The commit history can then be edited
before submission to meet the requirements mentioned above. History editing can be achieved in
multiple ways. Some methods are as follows:
- Git interactive rebasing. [[Guide](https://git-rebase.io/)]
- A stacked patch tool such as [Stacked-Git](https://stacked-git.github.io/).
### Commit Messages
The commit message (after editing the commit history) [should follow][commit1] [the][commit2] [best
practices][commit3]. The general idea is to treat the commit message as an email addressed to the
maintainers introducing the change. The first line of the commit becomes part of the subject line
and the 3rd line onwards becomes the body of the email. The body itself is optional. However, the
general idea is that the commit message should contain all the information you want to convey to the
maintainers and users about the changes you introduced in the commit. It's up to you to decide how
long the commit message has to be to achieve this.
[commit1]: https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project
[commit2]: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
[commit3]: https://initialcommit.com/blog/git-commit-messages-best-practices#general-commit-message-guidelines
### Communicating the Changes
Contributions are accepted as **email patches** or **pull requests**. Changes can be [emailed as
patches][gitemail] to the [project mailing list][maillist]. Make sure that you change the subject
line to:
```
[PATCH KeyBoxen v2] Add this feature
```
This can be automated by running the following command within the repo:
```sh
git config format.SubjectPrefix="PATCH KeyBoxen"
```
The other method of accepting contributions are [**pull requests**][reqpull]. Please note that
**this is not the same as pull requests of GitHub or GitLab**. However, it's easier. All you need is
a public and online copy of your repo on any git hosting service. The request-pull message can be
mailed to us using a regular email service.
[gitemail]: https://git-send-email.io/
[reqpull]: https://git-scm.com/docs/git-request-pull
## Attribution
This guide is based on the **contributing-gen**. [Make your own](https://github.com/bttger/contributing-gen)!