From 3b6f24dd17ecc0f950f121ee94c40b72fa5a08f3 Mon Sep 17 00:00:00 2001 From: Valentin Tolmer Date: Mon, 30 Oct 2023 22:38:44 +0100 Subject: [PATCH] github: Add CONTRIBUTING guidelines --- CONTRIBUTING.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..eef0f4e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,97 @@ +# How to contribute to LLDAP + +## Did you find a bug? + + - Make sure there isn't already an [issue](https://github.com/lldap/lldap/issues?q=is%3Aissue+is%3Aopen) for it. + - Check if the bug still happens with the `latest` docker image, or the `main` branch if you compile it yourself. + - [Create an issue](https://github.com/lldap/lldap/issues/new) on GitHub. What makes a great issue: + - A quick summary of the bug. + - Steps to reproduce. + - LLDAP _verbose_ logs when reproducing the bug. Verbose mode can be set through environment variables (`LLDAP_VERBOSE=true`) or in the config (`verbose = true`). + - What you expected to happen. + - What actually happened. + - Other notes (what you tried, why you think it's happening, ...). + +## Are you requesting integration with a new service? + + - Check if there is already an [example config](https://github.com/lldap/lldap/tree/main/example_configs) for it. + - Try to figure out the configuration values for the new service yourself. + - You can use other example configs for inspiration. + - If you're having trouble, you can ask on [Discord](https://discord.gg/h5PEdRMNyP) + - If you succeed, make sure to contribute an example configuration, or a configuration guide. + - If you hit a block because of an unimplemented feature, go to the next section. + +## Are you asking for a new feature? + + - Make sure there isn't already an [issue](https://github.com/lldap/lldap/issues?q=is%3Aissue+is%3Aopen) for it. + - [Create an issue](https://github.com/lldap/lldap/issues/new) on GitHub. What makes a great feature request: + - A quick summary of the feature. + - Motivation: what problem does the feature solve? + - Workarounds: what are the currently possible solutions to the problem, however bad? + +## Do you want to work on a PR? + +That's great! There are 2 main ways to contribute to the project: documentation and code. + +### Documentation + +The simplest way to contribute is to submit a configuration guide for a new +service: it can be an example configuration file, or a markdown guide +explaining the steps necessary to configure the service. + +We also have some +[documentation](https://github.com/lldap/lldap/tree/main/docs) with more +advanced guides (scripting, migrations, ...) you can contribute to. + +### Code + +If you don't know what to start with, check out the +[good first issues](https://github.com/lldap/lldap/labels/good%20first%20issue). + +Otherwise, if you want to fix a specific bug or implement a feature, make sure +to start by creating an issue for it (if it doesn't already exist). There, we +can discuss whether it would be likely to be accepted and consider design +issues. That will save you from going down a wrong path, creating an entire PR +before getting told that it doesn't align with the project or the design is +flawed! + +Once we agree on what to do in the issue, you can start working on the PR. A good quality PR has: + - A description of the change. + - The format we use for both commit titles and PRs is: + `tag: Do the thing` + The tag can be: server, app, docker, example_configs, ... It's a broad category. + The rest of the title should be an imperative sentence (see for instance [Commit Message + Guidelines](https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53)). + - The PR should refer to the issue it's addressing (e.g. "Fix #123"). + - Explain the _why_ of the change. + - But also the _how_. + - Highlight any potential flaw or limitation. + - The code change should be as small as possible while solving the problem. + - Don't try to code-golf to change fewer characters, but keep logically separate changes in + different PRs. + - Add tests if possible. + - The tests should highlight the original issue in case of a bug. + - Ideally, we can apply the tests without the rest of the change and they would fail. With the + change, they pass. + - In some areas, there is no test infrastructure in place (e.g. for frontend changes). In that + case, do some manual testing and include the results (logs for backend changes, screenshot of a + successful service integration, screenshot of the frontend change). + - For backend changes, the tests should cover a significant portion of the new code paths, or + everything if possible. You can also add more tests to cover existing code. + - Of course, make sure all the existing tests pass. This will be checked anyway in the GitHub CI. + +### Workflow + +We use [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow): + - Fork the repository. + - (Optional) Create a new branch, or just use `main` in your fork. + - Make your change. + - Create a PR. + - Address the comments by adding more commits to your branch (or to `main`). + - The PR gets merged (the commits get squashed to a single one). + - (Optional) You can delete your branch/fork. + +## Reminder + +We're all volunteers, so be kind to each other! And since we're doing that in our free time, some +things can take a longer than expected.