First of all, thanks for taking the time to contribute to Textual!
You can contribute to Textual in many ways:
To make a code or documentation contribution you will need to set up Textual locally. You can follow these steps:
poetry shell
to create a virtual environment for the dependenciesmake setup
to install all dependenciestextual --version
pre-commit install
(Read this if the command make
doesn't work for you.)
Once you have Textual installed, run the Textual demo to get an impression of what Textual can do and to double check that everything was installed correctly:
python -m textual
Read any issue instructions carefully. Feel free to ask for clarification if any details are missing.
Add docstrings to all of your code (functions, methods, classes, ...). The codebase should have enough examples for you to copy from.
Write tests for your code.
Before you open your PR, please go through this checklist and make sure you've checked all the items that apply:
CHANGELOG.md
make format
)make test
)(Read this if the command make
doesn't work for you.)
If you change the documentation, you will want to build the documentation to make sure everything looks like it should.
The command make docs-serve-offline
should start a server that will let you preview the documentation locally and that should reload whenever you save changes to the documentation or the code files.
(Read this if the command make
doesn't work for you.)
We strive to write our documentation in a clear and accessible way so, if you find any issues with the documentation, we encourage you to open an issue where you can enumerate the things you think should be changed or added.
Opening an issue or a discussion is typically better than opening a PR directly. That's because there are many subjective considerations that go into writing documentation and we cannot expect you, a well-intentioned external contributor, to be aware of those subjective considerations that we take into account when writing our documentation.
Of course, this does not apply to objective/technical issues with the documentation like bugs or broken links.
When you open a PR, your code will be reviewed by one of the Textual maintainers. In that review process,
The sole purpose of those interactions is to make sure that, in the long run, everyone has the best experience possible with Textual and with the feature you are implementing/fixing.
Don't be discouraged if a reviewer asks for code changes. If you go through our history of pull requests, you will see that every single one of the maintainers has had to make changes following a review.
Snapshot tests ensure that visual things (like widgets) look like they are supposed to.
PR #1969 is a good example of what adding snapshot tests looks like: it amounts to a change in the file tests/snapshot_tests/test_snapshots.py
that should run an app that you write and compare it against a historic snapshot of what that app should look like.
When you create a new snapshot test, run it with pytest -vv tests/snapshot_tests/test_snapshots.py
.
Because you just created this snapshot test, there is no history to compare against and the test will fail.
After running the snapshot tests, you should see a link that opens an interface in your browser.
This interface should show all failing snapshot tests and a side-by-side diff between what the app looked like when the test ran versus the historic snapshot.
Make sure your snapshot app looks like it is supposed to and that you didn't break any other snapshot tests.
If everything looks fine, you can run make test-snapshot-update
to update the snapshot history with your new snapshot.
This will write to the file tests/snapshot_tests/__snapshots__/test_snapshots.ambr
, which you should NOT modify by hand.
(Read this if the command make
doesn't work for you.)
Seems a little overwhelming? Join our community on Discord to get help!
Textual has a Makefile
file that contains the most common commands used when developing Textual.
(Read about Make and makefiles on Wikipedia.)
If you don't have Make and you're on Windows, you may want to install Make.
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。