🏅 Contributing!

Thank you for your interest in Transformer! Your contributions are highly welcome. 🎉

There are multiple ways to get involved:

Make sure you always follow our simple code of conduct. If you need help, please reach out to us by opening an issue.

Report a bug

Reporting bugs is one of the best ways to contribute. Before creating a bug report, please check that an issue reporting the same problem does not already exist. If there is such an issue, show your interest with an emoji reaction on the issue’s description, and add the results of your investigation (if any) in a comment.

To report a new bug, open a bug report describing the problem.

If you want to provide a fix along with your bug report, that’s great! In that case, please send us a pull request as described below in the Contribute code section.

Suggest a feature

To propose a new feature for Transformer, open a feature request and summarize the desired functionality and the problem you’re trying to solve.

Contribute code

Set up a dev environment

The only required dependency for local deployment is Poetry.

Once you have Poetry, you can simply call make to install all necessary dependencies and run all tests and linters. This mimics what happens in our continuous integration pipeline, so you won’t get surprised.

Conventions

  • All source code is formatted using black.
  • flake8 does not find any problems in the transformer module tree.
  • All non-private functions are reasonably covered by unit tests runnable with Pytest (via make test).
  • All user-facing APIs are clearly documented using Sphinx in docstrings (for developers) and in reST files in the docs/ directory (for users). See Documentation for details.
  • All user-facing changes are reported in 🕰 Changelog, along with a reference to the relevant pull request or issue identifiers.

Suggested workflow

  1. Check the list of open issues. Either assign yourself to an existing issue, or create a new one that you would like to work on. Describe the problem you’re trying to solve, and your ideas for solving it.

    It is always best to discuss your plans beforehand: it ensures that your contribution is in line with the goals of the project.

  1. Fork the repository on GitHub and clone your fork:

    $ git clone https://github.com/my-pseudo/transformer.git
    
  1. Create a feature branch, for example my-feature, starting from the master branch:

    $ git checkout -b my-feature
    

    Push that branch on your fork:

    $ git push -u origin my-feature
    
  2. Open a new pull request in draft mode, and explain what you are doing: which issue are you solving and how?

    Using the draft mode prevents from immediately sending a request for code review to all maintainers, so it’s useful when you don’t yet have all your code ready.

  1. Get the necessary tools: Set up a dev environment.

  2. Make commits of small, logical units of work. We should be able to use git bisect to find the origin of bugs. Make sure you sign-off on all your commits:

    $ git commit -s
    

    And finally, please write clear commit messages!

  1. Check that all tests (including your new ones) succeed, and that the linters are still happy:

    $ make test lint
    

    If this fails on your local machine, there is a good risk that it will also fail on Travis, preventing your pull request from being merged.

    Note

    If you notice that tests or linters are already failing when you clone the repository, please open a bug report! This would indicate that our developer environment or instructions are not general enough.

  2. Project maintainers may comment on your work as you progress. If they don’t and you would like some feedback, feel free to mention one of them in your pull request.

  1. As explained in the Release process section, in Transformer, each pull request merged in the master branch becomes a new release on PyPI. Therefore, a few files need to be updated with a new version number, and docs/Changelog.rst should probably contain a description of your contributions. Everything is explained in Release process, including the make prepare command that should do most of the work for you.

  2. You are welcome to add your name in our ✌ Project Contributors file (docs/Contributors.rst). This is of course optional, but we would be happy to remember and showcase the help you provided!

  3. When you are done, mark your draft pull request as Ready for review. This will automatically request a code review from all project maintainers.

    Make sure your contributions respect Transformer’s conventions before that!

  1. Your pull request must be approved 👍 by two project maintainers before it can be merged.

Thank you for your contributions!

Documentation

It is important that all features of Transformer are documented:

  • user-facing features, like new built-in plugins, new command-line options, or changes to the plugin API: if our users don’t know these features exist, they will not use them and Transformer will be less useful to them;
  • contributor-facing features, like internal APIs, design decisions, and contribution workflows: if our potential contributors struggle finding the right place to contribute, or cannot get a working development environment, the barrier of entry will be too high and the project will not benefit from their valuable contributions.

Transformer uses Sphinx to make the documentation accessible and readable to anyone with a web browser. It also makes it easy to link user documentation (in docs/*.rst) and contributor documentation (as docstrings in Transformer’s Python source files) when appropriate.

Sphinx is automatically installed during the Set up a dev environment step. You can easily build the documentation on your own machine by running make doc at the root of the repository. This converts the reST files under the docs/ directory into HTML files under docs/_build/html/, so you can do something like:

$ firefox docs/_build/html/index.html

to start browsing the documentation locally.

Note

Be careful not to track these generated HTML files with git. The reST files and docstrings are the only source of truth.

Commit messages

Ideally, your commit messages answer two questions: what changed and why?

The message’s first line should describe the “what”. The rest of the message (separated from the first line by an empty line) should explain the “why”.

Sign your work / DCO

All contributions to Transformer (including pull requests) must agree to the Developer Certificate of Origin (DCO) version 1.1. This is exactly the same one created and used by the Linux kernel developers: a certification by a developer that they have the right to submit their contribution to the project.

Simply submitting a contribution (commits) implies this agreement. However, please include a “Signed-off-by” line in every commit – that line is a conventional way to confirm that you agree with the DCO. You can do that easily with git’s -s option:

$ git commit -s

You can automate this with a git hook.

Have fun, and happy hacking!