mirror of https://github.com/nitnelave/lldap.git
98 lines
4.9 KiB
Markdown
98 lines
4.9 KiB
Markdown
# 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.
|