EuroPython 2023 sprint meta issue. Start here!

[rodrigogiraoserrao]

Welcome to the EuroPython 2023 Textual sprint!

First of all, thanks for your interest in contributing!
This meta issue lists some issues that we hand-picked for you to tackle during the sprint.
Take a look at the instructions below, pick an issue to tackle, and have fun!

Throughout the sprint, I (Rodrigo, @rodrigogiraoserrao) will be around to help you and some other maintainers may also be available to jump in when needed.
Also, if you join the Discord server you'll have access to many other Textual users and enthusiasts who may be able to lend you a hand.

Before contributing

If you want to participate in this sprint, 1+ year of Python experience is recommended.
You are also encouraged to go through the Textual tutorial, if you haven't yet, to ensure you have at least some understanding of what Textual does.

Setup

To develop Textual, you'll need to clone this repository.
Then, make sure you have Poetry installed and run poetry install --all to install all of the (dev) dependencies.

Make sure everything is working fine by running textual --version.

Good first issues

These issues were handpicked by us for you to tackle at the EuroPython sprint.
They should be self-contained and they aren't technically very demanding... but they will take time to tackle!

• CLOSED ** Add a Unicode digits display widget #2916 – add a new widget to Textual; peek at how Textual actually displays things in a terminal
• ** Add a marquee widget #2917 – ditto
• CLOSED ** Add Rule widget #2982 – ditto
• CLOSED ** Add a collapsible container widget #2918 – build a new compound widget: a widget built out of existing widgets
• Add an accordion widget #2919 – build a new compound widget: a widget built out of existing widgets (this one depends on the previous one)
• ** Add style variations to the progress bar widget #2920 – enhance a widget with more styles
• CLOSED ** Add a method to DirectoryTree that allows for reloading an individual node #2757 – enhance a widget with a new method
• CLOSED ** Extend OptionList so that an option's prompt can be replaced in some way #2603 – enhance a widget with a new method
• ** Add command widgets to Textual CLI #2921 – write an app for the Textual CLI
• CLOSED ** Extend textual colors to show named colours #2922 – modify an app from the Textual CLI
• CLOSED ** Send mouse move events to screen #2905 – fix a bug related to message bubbling
• CLOSED ** Switch should stop the Click event from bubbling #2366 – fix another bug related to message bubbling
• CLOSED ** Allow for empty CSS variable definitions #1849 – fix a bug with CSS parsing

** Someone already started working on this issue. You are still welcome to join them if you'd like to work together. Just talk to whoever is working on the issue you're interested in.

Guidelines

Here are some guidelines to keep in mind when contributing:

• Make sure to read the issue instructions carefully. For the EuroPython sprint, we picked some good first issues (listed in this meta-issue) that should be clear enough and sometimes even provide some hints. If something isn't clear, ask for clarification!

• 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.

  • If you are fixing a bug, make sure to add regression tests that link to the original issue.
  • If you are implementing a visual element, make sure to add snapshot tests. More on that, below.

Snapshot testing

Snapshot tests ensure that things like widgets look like they are supposed to.
PR #1969 is a good example of what adding snapshot tests means: 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 automatically.
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 it ran VS 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 that's the case, 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, that you should NOT modify by hand.

Before opening a PR

Please make sure that:

• the CHANGELOG.md was updated;
• your code was formatted with black (make format);
• all of your code has docstrings in the style of the rest of the codebase;
• your code passes all tests (make test); and
• you added documentation, when needed.

After opening a PR

When you open a PR, your code will be reviewed by one of the Textual maintainers.
In that review process,

• we will take a look at all of the changes you are making;
• we might ask for clarifications (why did you do X or Y?);
• we might ask for more tests/more documentation; and
• we might ask for some code changes.

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.

After everyone is happy with everything, your PR is merged and your contributions will be shipped in the next Textual release! 🥳 🎉

[github-actions]

Don't forget to star the repository!

Follow @textualizeio for Textual updates.