🎉 First and foremost, thanks for taking the time to contribute! 🎉
The following is a set of concise guidelines for contributing to MALib and its packages. Feel free to propose changes to this document in a pull request.
- Be respectful to other contributors.
- Keep criticism strictly to code when reviewing pull requests.
- If in doubt about conduct ask the team lead or other contributors.
We encourage all forms of contributions to MALib, not limited to:
- Code review and improvement
- Community events
- Blog posts and promotion of the project
- Feature requests
- Patches
- Test cases
In addition to following the setup steps in the README, you'll need to install the [dev]
dependencies.
pip install -e .[dev]
Once done, you're all set to make your first contribution!
Please take a look at the current open issues to see if any of them interest you. If you are unsure how to get started please take a look at the README.
Please take care in using good commit messages as they're useful for debugging, reviewing code, and generally just shows care and quality. How to Write a Git Commit Message <https://chris.beams.io/posts/git-commit/> provides a good guideline. At a minimum,
- Limit the subject line to 50 characters
- Capitalize the subject line
- Do not end the subject line with a period
- Use the imperative mood in the subject line
- If only changing documentation tag your commit with
[ci skip]
- Do your best to see that your code compiles locally.
- Run
make format
. See [Formatting](#Formatting). - Do not push to
main
. Instead make a branch and a pull request <#submission-of-a-pull-request>
- Rebase on master
- Run
make test
locally to see if all test cases pass - If you change platform code, you are responsible to ensure all tests and all examples still run normally.
- Be sure to include new test cases if introducing a new feature or fixing a bug.
- Update the documentation and apply comments to the public API. You are encouraged to add usage cases.
- Update the
CHANGELOG.md
addressing what changes were made for the current version and make sure to indicate the PR # linking the changes. - For PR description, describe the problem and add references to the related issues that the request addresses.
- Request review of your code by at least two other contributors. Try to improve your code as much as possible to lessen the burden on others.
- Do _not_ keep long living branches. Branches are for a specific task. They should not become a sub repository.
- After your PR gets approved by at least other contributors you may merge your PR.
- Please enable squashing on your Pull Request before merging, this helps keep every commit on master in a working state and aids bisecting when searching for regressions.
In the body, give a reason for the pull request and tag in issues that the pull request solves. The WIP:
is for pull requests that should raise discussion but are not in review state.
You are encouraged to review other people's pull requests and tag in relevant reviewers.
- Always raise issues in GitLab. Verbal discussion and reports are helpful but _not_ enough. Put things in writing please.
- Raise specific, single-topic issues. If you find yourself having to use "and" in the issue title, you most likely want to create more than one.
Before reporting a bug please check the list of current issues to see if there are issues already open that match what you are experiencing.
When reporting a bug, include as much info as necessary for reproducing it. If you find a closed issue that appears to be the same problem you are experiencing; please open up a new issue referencing the original issue in the body of the new issue.
Tag the issue as a bug.
Before requesting a feature please check the list of current issues to see if there is already a feature request similar to yours. Also, make sure that the feature you are requesting is not a bug. If it a bug see [Reporting Bugs](Reporting-Bugs).
Describe as best you can what the feature does and why it is useful. Visual aids help with understanding more complex features.
Tag the issue as a feature request using enhancement and if it takes more than a few lines to describe also tag with discussion.
- Always run
make format
before committing.
The project follows a strict format requirement for python code. We made a decision early on in the project to use Black <https://github.com/psf/black>. This makes formatting consistent while eliminating bike shedding <http://bikeshed.com/>.
If you do not already have it please install it via pip install black
.
Formatting guarantees that your code will pass the CI formatting test case.
[TODO]