Quick Start

The following steps will guide through the process of setting up your local Python environment to work on your first contribution to the project.

Pre-requisites

  • The project uses Astral’s uv to manage its dependencies. Follow the instructions on their website to install.

  • Make sure your Python version is supported. Refer to the pyproject.toml file for details.

  • Make sure to read the code style guidelines

  • Make sure to read the pull request guidelines

Step 1. Fork the Repository

Step 2. Clone the Repo: Clone the repository to your local machine using:

git clone https://github.com/yourusername/repo.git

Step 3. Set up the local environment

cd <to-your-local-repo>
source .venv/bin/activate
make env  # or: uv sync --all-groups
make install_pre_commit_hooks

Step 4. Create a Branch: Create a new branch for your feature or bug fix:

git checkout -b feature/your-feature-name

Step 5. Make Changes: Implement your changes. Ensure that your code adheres to the project’s coding style and conventions.

Step 6. Write Tests: If applicable, write tests for your changes to ensure they work as expected.

Step 7. Test your Changes:

  • Make sure to run the tests with make test. See Testing for details.

  • To test your changes manually it’s recommended to run the Textual dev console

# console 1
textual console

# console 2
JIRA_TUI_CONFIG_FILE=path/to/config.yaml textual run --dev src/jiratui/cli.py ui

or,

# console 2
JIRA_TUI_CONFIG_FILE=path/to/config.yaml textual run --dev src/jiratui/app.py

This will allow you to test the application and see live logs in the other terminal console.

Important

If you make changes to the documentation then you can generate the docs locally to test your changes. You do that by running:

make make-docs

For more detail shead over to Writing Documentation.

Step 8. Update the CHANGELOG: make sure to update the CHANGELOG to record the changes.

Step 9. Commit Your Changes: Commit your changes with a clear and descriptive message:

git commit -m "Add feature: your-feature-name"

Step 10. Push Your Changes: Push your changes to the repository:

git push origin feature/your-feature-name

Step 11. Create a Pull Request: After pushing, go to your forked repository on GitHub, and you will see a prompt to create a pull request. Click on “Compare & pull request,” add a description of your changes, and submit the PR.

Great! now you know the basics of how to set up your local environment to start contributing to the project.

The next step is to familiarize yourself with the basic concepts of the application, including the use cases supported by the application, the architecture that supports these use cases, the different UI components and the Jira API implementation.