Contributing to Harlequin

Thanks for your interest in Harlequin! Harlequin is primarily maintained by Ted Conbeer, but he welcomes all contributions!

Sponsoring Harlequin

Please consider sponsoring Ted, so he can continue to dedicate time to developing and supporting Harlequin.

Providing Feedback

We’d love to hear from you! Start a Discussion or open an Issue to request new features, report bugs, or say hello.

Contributing Code

If you would like to contribute code to Harlequin, that is fantastic! Ted would love to support you. Please reach out by opening or commenting on an Issue so we can provide more tactical guidance. If you’d like to create a database adapter for Harlequin, the next page provides a guide.

Watch this video for an overview of the end-to-end process for contributing to Harlequin, from clone to PR:

General advice is below:

Opening PRs

  1. PRs should be motivated by an open issue. If there isn’t already an issue describing the feature or bug, open one. Do this before you write code, so you don’t waste time on something that won’t get merged.
  2. Ideally new features and bug fixes would be tested, to prevent future regressions. Textual provides a test harness that we use to test features of Harlequin. You can find some examples in the tests directory of this project. Please include a test in your PR, but if you can’t figure it out, open a PR to ask for help.
  3. Please include an entry in CHANGELOG.md that explains the change and links to the open issue that this change closes. Feel free to credit yourself as a contributor.
  4. Open a PR from your fork to the main branch of tconbeer/harlequin. In the PR description, link to the open issue, and then write a few sentences about why you wrote the code you did: explain your design, etc.
  5. Ted may ask you to make changes, or he may make them for you. Don’t take this the wrong way — he values your contributions, but he knows this isn’t your job, either, so if it’s faster for him, he may push a commit to your branch or create a new branch from your commits.

Setting up Your Dev Environment and Running Tests

  1. Install Poetry v1.2 or higher if you don’t have it already. You may also want to install make.
  2. Fork this repo, and then clone the fork into a directory (let’s call it harlequin), then cd harlequin.
  3. Use poetry install --sync to install the project (editable) and its dependencies (including all test and dev dependencies) into a new virtual env.
  4. Use poetry shell to spawn a subshell with the virtual environment activated.
  5. Run pre-commit install to install pre-commit hooks.
  6. Type make to run all tests and linters, or run pytest, black ., ruff . --fix, and mypy individually.

Inspecting and Updating Snapshot Tests

Many changes to Harlequin will cause snapshot tests to fail. You will need to inspect the failures and update the “ground truth” snapshots in order for tests to pass (see the video for more info). The steps are:

  1. Run pytest to generate test failures. If snapshots do not match, a file called snapshot_report.html will be generated in the root of the project directory.
  2. Open snapshot_report.html in a browser and inspect the before and after for each failing snapshot. The “Show Difference” toggle is especially handy to quickly find the change that caused the failure. Note: sometimes invisible changes (like changes to class names in the SVG) can cause test failures. In this case, after toggling “Show Difference”, you should see a blank, black square.
  3. If all of the new snapshots are showing the expected result, run pytest --snapshot-update, and confirm the result of that command.
  4. Check in any changes to the data files in the tests/functional_tests/__snapshots__ directory.
  5. Including a screenshot of any changes in your PR description is much appreciated!