Skip to content

Latest commit

 

History

History
265 lines (192 loc) · 11.9 KB

CONTRIBUTING.md

File metadata and controls

265 lines (192 loc) · 11.9 KB
Raw

Contributing

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.

Foreword

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 😃

Table of Contents

Code of Conduct

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.

Issues

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:

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.

Security 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.

Development Setup

Prerequisites

In order to build muttlib you will need to have installed the following system packages:

On Ubuntu:

  • libkrb5-dev
  • libsasl2-dev

On Fedora/CentOS:

  • krb5-devel
  • cyrus-sasl-devel

Poetry

muttlib is packaged and developed using poetry. Follow these steps to install it and get familiar with the quickstart.

Installation

Start by cloning the repo

git clone git@gitlab.com:mutt_data/muttlib.git

Then install all minimal dependencies for development use:

cd muttlib
poetry install

Pre-Commit for Version Control Integration

We 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-push

Style guide

muttlib 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

Docstrings

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] option. To run the coverage, use the following command:

poetry run interrogate muttlib -c pyproject.toml

or for more details use the -vv flag:

poetry run interrogate muttlib -c pyproject.toml -vv

As 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.

Testing

muttlib uses the pytest framework to test muttlib.

To run the default test suite run this:

poetry run pytest

Note that some tests may depend on external dependencies not installed with [dev] if you want to run the full set of tests use [all] instead, running this:

poetry install -E all

Run 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 tests

Regression testing

Regression test ensures new changes have not broken previously working features.

Documentation

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 html

And open docs/build/html/index.html on your browser of choice.

Alternatively you can see the docs for the master branch here.

Versioning

muttlib uses SemVer. To keep things easy, we've included bump2version as a dev dependency. You can use poetry run bump2version minor to increase the minor number.

Please remember to bump the version when submitting your PR!

Deprecation

Before fully deprecating a feature or making a breaking change, give users a DeprecationWarning and enough time for them to migrate their code.

Decorator

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 + y

You 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):
    pass

You 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 + y

Release

Deprecation warning must be added in minor releases and EOL will be on the next major releases.

PRs

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

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

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.

CI/CD jobs

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.

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

Rules of Thumb

  • Important changes should be mentioned in the README.md
  • Documentation must be updated.
  • Every change should be present in the CHANGELOG.md