Skip to content

Contributing to the puntgun#

Thank you for considering making this tool better.

You'll need a GitHub account to participate in contributing, which can be an obstacle, and I apologize for that. You can also email me (I generally check email once a week), but it is difficult for me personally to reply to everyone appropriately, so please consider this as a backup option only.

There is no strict limit to how and what you can contribute, here are a few ways we can think of.

Programming aspect#

  • Improving unsatisfied code: There are some unsatisfactory pieces of logic in the code, they work, but they deserve to be better. You can find them by searching for IMPROVE marks in the code.
  • Join the discussion about or deal with unclosed issues.
  • Develop new features to this tool (and we recommend developing in the steps described below).
  • Improve CI/CD process.
  • Add more test cases.

For local development, please read this part. For security and vulnerability reports, please read this documentation.

Non-programming aspect#

  • Improving documentation:

    • Make documentation easier to understand by changing expressions.
    • Fixing syntax and typo errors in documentation.
    • Add more necessary details for the user to know the specific behavior of the tool without having to read the code.

  • Join the community on the GitHub:

Tell us what you intend to do before finishing it#

When you decide to make programming aspect contributions, we expect you to indicate in the corresponding issue or new issue that you intend to do this and how you intend to implement it, like this article. Industry experience tells us that shift-left checks and discussions is good for software development, for example we can provide more relevant knowledge, project details and advice to help you do things better when we know what you want to do.

Of course there is no mandatory requirement (compliments of the freewheeling open source community!), the code for this project is open source under the MIT license, and you do not need to get anyone's permission to make changes to (your fork of) this project, you just need to make it work for your personal needs. If you feel that your changes will also benefit the upstream, you can submit a Pull Request to the upstream, and only then does the "contribution" begin.

PR should pass lint checks#

Remember to run pdm run lint and make sure all checks pass before creating Pull Request, the CI will fail if any lint tool complains.

Prepare for local development#

If you are not familiar with how to clone a project and submit a pull request using GitHub, please read this documentation from GitHub official.

This project requires Python version 3.10, please download a new one or upgrade your existing Python's version.

(Sorry to be abrupt, but... pipx is an excellent tool for managing executable python libraries, you may want to use it instead of pip for installing pypi-based executable tools. Almost all tools used in the project can be happily installed in this convenient way, though they will be well cared by other managing tools, so you need not manually install them while you using scripts. If you install them with pipx in addition to venv and PDM, you can use them anywhere, that is convenient.)

This project uses the PDM as package managing tool, if you are not skilled enough to use other package management tools to be compatible with the PDM configuration (scripts defined in pyproject.toml, etc.), install the PDM.

PDM will detect and reuses the virtualenv python environment under the project directory, so you can write code with your PDM-not-supported IDEs (PyCharm for example) in virtualenv style, while using PDM truly managing everything via terminal.

Now simply install all dependencies with pdm install. All set, now you can play with the code or get your hands dirty to make things happen.

Scripts and tools for development#

All development scripts are defined under [tool.pdm.scripts] section in pyproject.toml.

Run tests#

1
pdm run test

This project uses pytest as the unit testing framework, which will be installed with development dependencies. Test cases are written under ./tests directory with test_ prefix.

1
pdm run coverage

This script will run the test suite with pytest while generating a html format coverage report with coverage.py.

Linting#

Warning Running this script will actually change the code, make sure commit your code before running.

1
pdm run lint

This project uses pre-commit for linting, it will help us to manage other linting tools. Check .pre-commit-config.yaml under root directory to see pre-commit hooks configuration. Currently, this project uses:

  • black for code style automatic formatting.
  • isort for import statements sorting.
  • codespell for typo checking.
  • flake8 for common Python programming problem checking.
  • mypy for static type hint scanning.

Render the documentation website#

1
pdm run doc

This project uses MkDocs as documentation website framework, with Material for MkDocs as website theme. They will also be installed with development dependencies. Documentation source is written in Markdown format, under ./docs directory.