Thanks for your interest in contributing to muttlib 🎉. These are the guidelines for contributions. Reading them will help you get started on how to make useful contributions.
This guide is not final. It will evolve over time, as we learn and add new voices to the project. Check it from time to time and feel free to make suggestions 😃
- Contributing
One of our core values at Mutt is that we are an open team. We all make mistakes and need help fixing them. We foster psychological safety. We clearly express it when we don’t know something and ask for advice.
We expect everyone contributing to muttlib to follow this principle. Be kind, don't be rude, keep it friendly; learn, teach, ask, help.
Before submitting an issue, first check on the issues tracker if there is already one trying to cover that topic, to avoid duplicates. Otherwise we invite you to create it. And if you feel that your issue can be categorized you can use these labels:
| name | description |
|---|---|
bug |
Report a new bug or Look for existing bug issues |
feature-request |
Request for a new feature or find existingfeature-requests |
enhancement |
Propose an enhancement or Find existing proposals for enhancement |
discussion |
Start a new discussion or Search for existing discussion issues. |
If you find a security related bug or any kind of security rellated issue, please DO NOT file a public issue. Sensitive security-related issues should be reported to privately to the repo owner along with a PoC if possible. You can send us an email and we'll go from there.
In order to build muttlib you will need to have installed the following system packages:
On Ubuntu:
libkrb5-devlibsasl2-dev
On Fedora/CentOS:
krb5-develcyrus-sasl-devel
muttlib is packaged and developed using poetry. Follow these steps to install it and get familiar with the quickstart. Make sure to install the version currently specified at the start of the lockfile (e.g. 1.6.1).
Start by cloning the repo
git clone [email protected]:MuttData/muttlib.gitThen install all minimal dependencies for development use:
cd muttlib
poetry installWe use pre-commit to run several code scans and hooks like linters and formatters, defined in .pre-commit-config.yaml, on each staged file that make the development cycle easier.
To install pre-commit hooks run
poetry run pre-commit install
poetry run pre-commit install -t pre-pushmuttlib follows PEP8.
If you installed the pre-commit hooks you shouldn't worry too much about style, since they will fix it for you or warn you about styling errors. We use the following hooks:
- black: An opinionated code formatting tool that ensures consistency across all projects using it
- mypy: a static type checker for Python
- pylint: a source code, bug and quality checker
We use either numpy style or google style docstring formatting. It's usually good to include the following docstrings:
- Module level docstring giving a general overview of what it does.
- It may include TODOs
- It may include examples
- Class dosctrings explaining what it is
- Method/functions to explain what it does and what it's parameters are
As an additional tool, muttlib incorporates interrogate to analyze the docstring coverage. interrogate is a dependency installed with dev dependency group (poetry install --with dev). To run the coverage, use the following command:
poetry run interrogate muttlib -c pyproject.tomlor for more details use the -vv flag:
poetry run interrogate muttlib -c pyproject.toml -vvAs a final result, interrogate will report if the current docstring coverage has passed or not the fail-under parameter configured in the pyproject.toml file.
muttlib uses the pytest framework to test muttlib.
To run the default test suite run this:
poetry run pytestNote that some tests may depend on external dependencies not installed with --with dev if you want to run the full set of tests use [all] instead, running this:
poetry install -E allRun coverage:
poetry run pytest --cov-report html:cov_html --tb=short -q --cov-report term-missing --cov=. tests/That should output a short summary and generate a dir cov_html/ with a detailed HTML report that can be viewed by opening index.html in your browser.
To run the tests with nox:
poetry run nox --session testsRegression test ensures new changes have not broken previously working features.
muttlib uses Sphinx to autogenerate it's docs that are automatically built from docstrings and pushed by the CI jobs. Check the style guide section for notes on docstrings. Pushing all the docs is too cumbersome. You can generate them locally like so:
poetry install -E all
cd docs
make htmlAnd open docs/build/html/index.html on your browser of choice.
Alternatively you can see the docs for the master branch here.
muttlib uses SemVer. To keep things easy, we've included bump2version as a dev dependency. For example, you can use poetry run bump2version minor to increase the minor number.
Please remember to bump the version when submitting your PR!
Before fully deprecating a feature or making a breaking change, give users a DeprecationWarning and enough time for them to migrate their code.
muttlib uses deprecated decorators to implement DeprecationWarning.
Add a DeprecationWarning considering indicate:
- How to achieve similar behavior if an alternative is available or a reason for the deprecation if no clear alternative is available.
- The versions number when the functionality was deprecated and when the EOL will be.
To do this, decorate your deprecated function with @deprecated decorator:
from deprecated import deprecated
@deprecated
def some_old_function(x, y):
return x + yYou can also decorate a class or a method:
from deprecated import deprecated
class SomeClass(object):
@deprecated
def some_old_method(self, x, y):
return x + y
@deprecated
class SomeOldClass(object):
passYou can give a "reason" message to help the developer to choose another function/class:
from deprecated import deprecated
@deprecated(reason="use another function")
def some_old_function(x, y):
return x + yDeprecation warning must be added in minor releases and EOL will be on the next major releases.
Also called MRs (Merge Requests) in gitlab.
muttlib development follows a simple workflow:
- Assign yourself an issue
- If there's none, create it
- If you can't assign it yourself, ask someone to do it for you
- Create a new branch with a descriptive name
- Push to the remote
- Open a WIP PR to allow discussion and let others know where you're at with the issue
- Work on it 🤓
- When ready change the PR to RFC
- Make sure you run the pipelines once the PR leaves Draft mode, i.e on the Merge Result..
- You'll need at least one approval to merge
- Merge will be disabled if the CI/CD pipelines are failing
- If you can't merge it yourself, ask your last approver to merge it
- Please squash the commits and delete the branch
- Congrats and thanks for your contribution 🎉
Please keep PRs minimal. Try to keep the modified files to the bare needed for the issue you are working on. This will make the PR's changes more readable and allow for a quicker interaction with reviewers.
WIP stands for Work in Progress. WIP PRs are not yet ready to be merged. They allow for:
- Other project members to know you are working on something
- Early feedback, e.g. if you are doing something wrong or they see a problem down the road with your approach
You can tag a PR as WIP using the WIP: prefix on you PR title.
RFC stands for Request for Comments. It means you consider the issue is solved by the code in the PR and are asking people to review your changes.
All commits pushed to branches in pull requests will trigger CI jobs that install muttlib in a gitlab-provided docker-env and all the extras, run all tests and check for linting. Look at .gitlab-ci.yml for more details on this and as well as the official Gitlab's docs. Note that only PRs that pass the CI will be allowed to merge.
We use mypy to generate a codebase type checking coverage report and check for a minimum allowable value for line-rate metric. In case you would line to increase this target value, please change value of the enviroment variable set in the .gitlab-ci.yml file as MIN_LINE_RATE.
NOTE: If your commit message contains [ci skip] or [skip ci], without capitalization, the job will be skipped i.e. no CI job will be spawned for that push.
Alternatively, one can pass the ci.skip Git push option if using Git 2.10 or newer: git push -o ci.skip more info in here.
IMPORTANT:. If you skip the CI job it will not disable the option to do the merge, be careful when doing this.
Important note on coverage: A regex that captures the output from pytest-cov has been set from Settings -> CI/CD -> General Pipelines -> Test coverage parsing
- Important changes should be mentioned in the README.md
- Documentation must be updated.
- Every change should be present in the CHANGELOG.md