Contributing to Harlequin
Thanks for your interest in Harlequin! Harlequin is primarily maintained by Ted Conbeer, but he welcomes all contributions and is looking for additional maintainers!
If you would like to contribute code to Harlequin, that is fantastic! We 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:
- 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.
- 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
testsdirectory 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.
- 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.
- Open a PR from your fork to the
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.
- 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
- Install Poetry v1.2 or higher if you don’t have it already. You may also want to install
- Fork this repo, and then clone the fork into a directory (let’s call it
poetry install --syncto install the project (editable) and its dependencies (including all test and dev dependencies) into a new virtual env.
poetry shellto spawn a subshell with the virtual environment activated.
pre-commit installto install pre-commit hooks.
maketo run all tests and linters, or run
ruff . --fix, and
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:
pytestto generate test failures. If snapshots do not match, a file called
snapshot_report.htmlwill be generated in the root of the project directory.
snapshot_report.htmlin 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.
- If all of the new snapshots are showing the expected result, run
pytest --snapshot-update, and confirm the result of that command.
- Check in any changes to the data files in the
- Including a screenshot of any changes in your PR description is much appreciated!