textual icon indicating copy to clipboard operation
textual copied to clipboard

[Doc] Improvements to the Setup Section in `CONTRIBUTING.md`

Open starry48 opened this issue 4 months ago • 1 comments

I've noticed there are few areas in the Setup section of CONTRIBUTING.md that could be clarified or updated to become more beginner-friendly, especially those new to Poetry or Textual. Here are the suggested improvements:

  1. Poetry Installation Link Redirecting to the instructions
  • The current link in the first step to install poetry takes users to Poetry's homepage rather than the installation instructions
  • Suggestions: Update it brings users directly to the instructions page of the website
  1. poetry shell command needs prerequisites installed
  • Running the poetry shell command assumes users have the packages installed for the command to work, which may not be true to beginners
  • Suggestion: Another command that doesn't require these installations but still opens the virtual environment is poetry env activate
  1. Clarify textual --version requires poetry run
  • Newcomers to the project might miss that they need the poetry run prefix command
  • Suggestion: Add poetry run to the textual --version command
  1. Adding how to Run examples
  • After setup, beginners might wonder how to test an example script
  • Suggestion: Include another step which explains to use the poetry run python <SCRIPT_NAME.py> to execute an example in the examples folder

starry48 avatar Aug 13 '25 23:08 starry48