Skip to content

Contributing

Any contribution is welcome! This document provides guidelines for contributing to the bitbucket-jira-cli project.

Table of Contents

Getting Started

Prerequisites

  • Python 3.10 or higher
  • Git
  • uv (Python package manager)
  • jq (for JSON processing)

Install jq

sudo apt-get install jq

Install uv

Following the uv installation guide:

curl -LsSf https://astral.sh/uv/install.sh | sh

Add shell completion (optional):

echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

Project Setup

  1. Fork and Clone the Repository
git clone https://github.com/Spenhouet/bitbucket-jira-cli.git
cd bitbucket-jira-cli
  1. Install Dependencies
uv sync --all-groups

This will:

  • Create a virtual environment
  • Install all dependencies (including development dependencies via dependency groups)

  • Install the project in editable mode

  • Verify Installation

uv run bitbucket-jira-cli --help
uv run bj --help

Development Workflow

Running the Application

# Run with uv (recommended)
uv run bitbucket-jira-cli [commands]
uv run bj [commands]

# Or activate the virtual environment
source .venv/bin/activate
bitbucket-jira-cli [commands]

Adding Dependencies

# Add runtime dependency
uv add package-name

# Add development dependency (to dev group)
uv add --group dev package-name

# Add to custom dependency group
uv add --group group-name package-name

Updating Dependencies

# Update all dependencies
uv sync --upgrade

# Update specific dependency
uv sync --upgrade-package package-name

Testing

We use pytest for testing. Tests are located in the tests/ directory.

Running Tests

# Run all tests
uv run pytest

# Run tests with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_basic.py

# Run specific test
uv run pytest tests/test_basic.py::test_package_imports

Writing Tests

  1. Create test files in the tests/ directory with the prefix test_
  2. Follow naming conventions: test_*.py files, test_* functions
  3. Use descriptive test names that explain what is being tested
  4. Add docstrings to explain complex test scenarios

Example test structure:

def test_feature_description() -> None:
    """Test that the feature works as expected."""
    # Arrange
    input_data = "test input"

    # Act
    result = function_under_test(input_data)

    # Assert
    assert result == expected_output

Documentation

The docs site is authored as Material for MkDocs and built with Zensical (mkdocs.yml, docs/). Install the docs toolchain with uv sync --group docs, then:

uv run zensical serve            # live preview at http://127.0.0.1:8000
uv run zensical build --strict   # production build into site/

The command reference under docs/reference/ is generated from the live CLI, so do not edit those pages by hand. The generator also regenerates the reference section of the mkdocs.yml nav. After changing any command, flag, or help string, regenerate and commit both:

uv run python scripts/gen_cli_docs.py

Hand-written pages (the landing page, intro, installation, usage, and the guides under docs/guides/) are edited normally. Extended command descriptions and examples live in the maps at the top of scripts/gen_cli_docs.py.

Code Quality

Linting with Ruff

We use ruff for Python linting and code formatting.

# Check code quality
uv run ruff check

# Auto-fix issues where possible
uv run ruff check --fix

# Check specific files or directories
uv run ruff check bitbucket_jira_cli/
uv run ruff check tests/

Code Style Guidelines

  • Line length: Maximum 100 characters
  • Docstring style: Google docstring convention
  • Import formatting: One import per line (enforced by ruff)
  • Type hints: Use type annotations for new code

Pre-commit Workflow

Before committing:

  1. Run linting: uv run ruff check
  2. Run tests: uv run pytest
  3. Fix any issues before committing

Release Process

Note: Only relevant for maintainers.

Automated Release

We use GitHub Actions for automated releases:

  1. Trigger Release Workflow

  2. Go to GitHub Actions tab

  3. Run "Release" workflow

  4. Choose version bump type (patch/minor/major) or specify custom version

  5. Automated Steps

  6. Updates version in pyproject.toml
  7. Runs tests and builds
  8. Creates Git tag
  9. Publishes to PyPI
  10. Creates GitHub release with auto-generated notes
  11. Publishes the multi-arch Docker image to Docker Hub

Pull Request Guidelines

Before Submitting

  1. Create a feature branch
git checkout -b feature/your-feature-name
  1. Run the full test suite
uv run ruff check
uv run pytest
uv build --no-sources  # Test build
  1. Update documentation if needed

PR Requirements

  • ✅ All tests pass (verified by CI)
  • ✅ Code passes linting (ruff check)
  • ✅ Descriptive PR title and description
  • ✅ Reference related issues if applicable
  • ✅ Update tests for new functionality
  • ✅ Update documentation for user-facing changes

Development Environment

  • IDE: VS Code with Python extension
  • Git client: Command line or your preferred GUI
  • Terminal: Any modern terminal with shell completion

VS Code Extensions

Recommended extensions for development:

  • Python (Microsoft)
  • Ruff (Astral Software)
  • GitLens (GitKraken)
  • markdownlint (David Anson)

Project Structure

bitbucket-jira-cli/
├── .github/workflows/      # CI/CD workflows
├── bitbucket_jira_cli/    # Main package
│   ├── __init__.py
│   ├── main.py            # CLI entry point (Typer app)
│   ├── bitbucket/         # Bitbucket API client + commands
│   ├── jira/              # Jira API client + commands
│   └── utils/             # Shared utilities (config, git, branch keys)
├── tests/                 # Test suite
├── pyproject.toml        # Project + ruff configuration
├── pyproject.toml        # Project configuration
├── uv.lock              # Dependency lock file
└── CONTRIBUTING.md       # This file

Getting Help

  • GitHub Issues: For bug reports and feature requests
  • GitHub Discussions: For questions and general discussion
  • Documentation: Check the README and code comments

Thank you for contributing to bitbucket-jira-cli! 🚀