Contributing

Contributions of all types are welcome, as long as they are made in a way that follows the Python Community Code of Conduct which we have adopted. Contributions can be small or large, address documentation or code, etc.

  • Bug report and suggestions for improvements are always welcome and may be done via the standard Github issues tab.

  • For very small contributions, such as correcting minor typos or phrasing, either submit an issue or, if you find it easier, write a short email.

For larger contributions, you can either use a pull request (if you feel comfortable in doing so), or simply attaching files to an issue, if your contribution essentially leaves the existing code unchanged. However, in both cases, before writing any code, please start by filing an issue. If you are using a pull request, please read the relevant section below.

Ideally, new contributions should be accompanied by one or more unit tests, or examples of usage.

If you submit code to the project, indicate if you wish your contribution to be recognized in a contributors list if your code is accepted.

Language of communication

This project, by its very nature, welcome contributors speaking any language. We realise that decisions about particular keyword choices, or phrasing of a “simplified traceback” in a given language may be subject to discussions amongst speakers of that language. For this reason, we welcome discussions on issues done in any language, as long as it is done respectfully and that a very brief description of the main point(s) are provided in English.

Before submitting a pull request

  • Make sure that all unit tests pass.

  • Your code contribution should likely include at least one additional unit test.

  • This project uses Black with default parameters for formatting. This means that some linter that strictly follow PEP 8 will give spurious warning messages. We use flake8 and set the maximum line length to 88 characters.

  • Your submission should not change the formatting of existing code.

  • Make sure that your local version is updated to the latest version on the masters branch of this repository before making your pull request.

Before you think of writing code to be submitted as a pull request, you should first file an issue about it. If possible, create a separate branch identified with the issue number.

New language contribution

If you are contributing to add a new language which includes translated tracebacks, you might want to include an adapted version of all the tests that show tracebacks (see tb_pyupper.py in tests/pyupper/) so that they can be included in this documentation.

You can use the existing functions to write a simple script that will help automate this process.

Todo

Give an example of how to do so.