Skip to content

Latest commit

 

History

History
56 lines (36 loc) · 3.38 KB

CONTRIBUTING.md

File metadata and controls

56 lines (36 loc) · 3.38 KB

How to contribute

Here are some guidelines on how to contribute to the PyMandel project.

We appreciate any contribution, from fixing a grammar mistake in a comment to implementing new functionality. Please read this section if you are contributing your work.

Being one of our contributors, you agree and confirm that:

  • The work is all your own.
  • Your work will be distributed under a BSD 3-Clause License once your pull request is merged.
  • You submitted work fulfils or mostly fulfils our styles and standards.

Please help us keep our issue list small by adding fixes: #{$ISSUE_NO} to the commit message of pull requests that resolve open issues. GitHub will use this tag to auto close the issue when the PR is merged.

Coding conventions

  • This is open source software. We endeavour to make the code as transparent as possible. Favour clarity over brevity.
  • We use and recommend Visual Studio Code with the Python Extension for development and testing.
  • Code should be documented in accordance with Sphinx docstring conventions.
  • Code should formatted using black (>= 20.8).
  • We use and recommend pylint (>=2.6.0) for code analysis.
  • We use and recommend bandit (>=1.7) for security vulnerability analysis.
  • Commits should be signed.
  • PyMandel uses Numba for JIT compilation, parallelisation and caching. This affords very significant performance enhancements over native interpreted Python, but does necessitate certain coding constraints in the affected module(s) (mandlebrot.py) - refer to the Numba documentation for further details.

Testing

We use python's native pytest framework for local unit testing, complemented by the Github Actions automated build and testing workflow. Code coverage is extremely limited at present so we welcome improvements.

Please write pytest examples for new code you create and add them to the /tests folder following the naming convention test_*.py.

We test on the following platforms:

  • Windows 11
  • MacOS (Sequoia)
  • Linux (Ubuntu 24.04 Noble Numbat)
  • Raspberry Pi OS (64-bit & 32-bit)

Submitting changes

Please send a GitHub Pull Request to PyMandel with a clear list of what you've done (read more about pull requests). Please follow our coding conventions (below) and make sure all of your commits are atomic (one feature per commit).

Always write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes should look like this:

$ git commit -m "A brief summary of the commit
> 
> A paragraph describing what changed and its impact."

Please use the supplied Pull Request Template.

Please sign all commits - see Signing GitHub Commits for instructions.

Thanks,

semuadmin