Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Types of Contributions¶

You can contribute in many ways:

Report Bugs¶

Report bugs at https://github.com/bpcreech/PyMiniRacer/issues.

If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Fix Bugs¶

Look through the GitHub issues for bugs. Anything tagged with "bug" is open to whoever wants to implement it.

Implement Features¶

Look through the GitHub issues for features. Anything tagged with "feature" is open to whoever wants to implement it.

Write Documentation¶

Python Mini Racer could always use more documentation, whether as part of the official Python Mini Racer docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback¶

The best way to send feedback is to file an issue at https://github.com/bpcreech/PyMiniRacer/issues.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!¶

Ready to contribute? Here's how to set up PyMiniRacer for local development.

Warning

1-2 hours.

Do a quick scan through the architecture guide before diving in.
Fork the PyMiniRacer repo on GitHub.
If you plan to change C++ code you should probably install at least clang-format and clang-tidy from the latest stable LLVM. While the PyMiniRacer build uses its own compiler (!) on most systems, our pre-commit rules rely on the system clang-format and clang-tidy. If your versions of those utilities do not match the ones PyMiniRacer uses on GitHub Actions, you may see spurious pre-commit errors.

If you're on a Debian-related Linux distribution using the LLVM project's standard apt packages, note that you will likely have to override /usr/bin/clang-format and /usr/bin/clang-tidy to point to the latest version, i.e., /usr/bin/clang-format-18 and /usr/bin/clang-tidy-18, respectively.

You can always silence local pre-commit errors with the -n argument to git commit. We check pre-commits on every pull request using GitHub Actions, so you can check for errors there instead.
Install just.
Install uv.

Run some of the following:

    # Set up a local clone of your fork:
    $ git clone git@github.com:your_name_here/PyMiniRacer.git
    $ cd PyMiniRacer/

    # build v8 and uv (this may take hours depending on your system!)
    $ just build
    # alternatively, to only build v8 and skip making the Python package:
    $ uv run --no-project builder/v8_build.py  # will install a DLL into src/py_mini_racer

    # test stuff:
    $ uv run pytest test

    # fix and lint any changes you make:
    $ just fix
    $ just lint

You can also play with your build in the Python REPL, as follows:

    $ uv run python
    >>> from py_mini_racer import MiniRacer
    >>> mr = MiniRacer()
    >>> mr.eval('6*7')
    42
    >>> exit()
    $ exit

Create a branch for local development::

    $ git checkout -b feature/name-of-feature
    # or:
    $ git checkout -b fix/name-of-fix

Now you can make your changes locally.

When you're done making changes, check that your changes pass the linter and the tests, including testing other Python versions:

   # automatically fix any trivial linting issues:
   $ just fix
   # check for remaining linting issues:
   $ just lint
   # if you changed C++ code, lint it (this takes a long time):
   $ just clang-tidy
   # look at the docs if you changed them:
   $ just serve-docs
   # build v8, and your change (this takes a long time):
   $ just build
   # test:
   $ just test
   $ just test-matrix

Commit your changes and push your branch to GitHub::

   $ git add .
   $ git commit -m "Your detailed description of your changes."
   $ git push origin name-of-your-bugfix-or-feature

(Optional) Run the GitHub Actions build workflow on your fork to ensure that all architectures work.
Submit a pull request through the GitHub website.

Pull Request Guidelines¶

Before you submit a pull request, check that it meets these guidelines:

The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.md.
The pull request should work for the entire test matrix of Python versions (just test-matrix).

Releasing `PyMiniRacer`¶

Releases for PyMiniRacer should be done by GitHub Actions on the official project repository.

Ordinary releases¶

To make an ordinary release from main:

Merge all changes into main on the official repository.

Pick the next revision number:

$ git fetch
$ git ls-remote origin | grep refs/heads/release
# observe the next available release version

Create a feature/... branch, and:
1. Update HISTORY.md with a summary of changes since the last release.
2. Update src/py_mini_racer/__about__.py with the new revision number.
3. Create and merge a pull request for this branch into main.

Create a release/... branch:

$ git checkout main
$ git pull
NEXT_RELEASE=the next tag, starting with the letter v. E.g., "v0.12.1".
$ git checkout -b "release/${NEXT_RELEASE}"
$ git push --set-upstream origin "release/${NEXT_RELEASE}"

Observe the build process on GitHub Actions. It should build and push docs and upload wheels to PyPI automatically.

Hotfix releases¶

To hotfix a prior release:

Prepare the fix as a feature branch as normal, and merge it into main.
Pick the next revision number. This will typically be a patch-version update on the current release name.

Create a new release branch for the hotfix:

BASE_RELEASE=the release you are hotfixing, starting with the letter v. E.g., "v0.12.0".
NEXT_RELEASE=the next tag, starting with the letter v. E.g., "v0.12.1".
$ git checkout "release/${BASE_RELEASE}"
$ git pull
$ git checkout -b "release/${NEXT_RELEASE}"

Hotfix the commit(s) created in step #1 onto the new release branch.
Create a version update commit:
1. Update HISTORY.md with a summary of changes since the last release.
2. Update src/py_mini_racer/__about__.py with the new revision number.
Commit and push the new release branch to GitHub.
Merge this branch into main. All content on release branches should be included in main.
Observe the build process on GitHub Actions. It should build and push docs and upload wheels to PyPI automatically.