Contributing¶

Thank you for your interest in contributing to miniflux-tui-py! This document provides guidelines and instructions for getting involved.

Code of Conduct¶

Please read our Code of Conduct before contributing. We are committed to providing a welcoming and inspiring community for all.

Development Setup¶

Prerequisites¶

Python 3.11 or later
uv - Fast Python package manager
Git

Setting Up Your Development Environment¶

Fork and clone the repository:

git clone https://github.com/YOUR_USERNAME/miniflux-tui-py.git
cd miniflux-tui-py

Install dependencies with uv:

uv sync --all-groups

This will install all development and documentation dependencies including pytest, ruff, pyright, and mkdocs.

Verify your setup:

uv run miniflux-tui --check-config

Making Changes¶

Creating a Feature Branch¶

Create a feature branch from main:

git checkout main
git pull origin main
git checkout -b feature/your-feature-name

Running Tests Locally¶

Before submitting a pull request, make sure all checks pass:

# Run linting with ruff
uv run ruff check miniflux_tui tests

# Format code
uv run ruff format miniflux_tui tests

# Type checking with pyright
uv run pyright miniflux_tui tests

# Run tests with coverage
uv run pytest tests --cov=miniflux_tui --cov-report=term-missing

All checks are also run automatically when you commit (via pre-commit hooks).

Code Style¶

Line length: 140 characters
Quotes: Double quotes
Formatting: Follow ruff/black style
Type hints: Add type hints where possible
Docstrings: Use Google-style docstrings

Commit Messages¶

Write clear, concise commit messages:

Add feature: brief description

Longer description of what changed and why.

Submitting Changes¶

Pre-Submission Checklist¶

✅ Code passes all checks (ruff check, ruff format, pyright, pytest)
✅ Tests have been written/updated for new functionality
✅ Documentation has been updated if needed
✅ CHANGELOG.md has been updated (see below)
✅ Commit messages are clear and descriptive

Creating a Pull Request¶

Push your branch to your fork:

git push origin feature/your-feature-name

Create a pull request on GitHub:
Go to the main repository
Click "New Pull Request"
Select your feature branch
Fill in a descriptive title and description
Reference any related issues

What to Expect¶

Automated checks will run (tests, linting, type checking)
A maintainer will review your code
We may request changes before merging
Once approved, your changes will be merged to main

Testing¶

Running Tests¶

# Run all tests
uv run pytest tests

# Run with coverage
uv run pytest tests --cov=miniflux_tui

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

# Run tests matching a pattern
uv run pytest tests -k "test_navigation"

Writing Tests¶

Place tests in the tests/ directory
Use test_*.py file naming convention
Use descriptive test function names
Tests should be independent and fast

Example:

import pytest
from miniflux_tui.api.models import Entry

def test_entry_properties():
    """Test Entry model properties."""
    entry = Entry(
        id=1,
        title="Test Entry",
        content="Test content",
        # ... other properties
    )
    assert entry.is_unread is True

Updating Documentation¶

Documentation is built with MkDocs and located in the docs/ folder.

Editing Docs¶

Edit files in the docs/ folder (Markdown format)
Preview locally:
```
uv run mkdocs serve
```
View at http://localhost:8000

Documentation Guidelines¶

Use clear, simple language
Include code examples where helpful
Keep the table of contents in mkdocs.yml updated
Use relative links between docs

Updating CHANGELOG¶

Keep the CHANGELOG.md updated with your changes.

Format your entry under the current "Unreleased" section:

## Unreleased

### Added
- New feature description

### Fixed
- Bug fix description

### Changed
- Breaking change description

We follow Keep a Changelog format.

Release Process¶

(For maintainers)

When ready to release:

Update version in pyproject.toml
Update CHANGELOG.md with version and date
Commit: git commit -m "Release v0.2.0"
Tag: git tag v0.2.0
Push: git push origin main --tags
GitHub Actions automatically publishes to PyPI and creates a GitHub Release

Getting Help¶

Check existing issues and discussions
Ask questions in GitHub Discussions
Report bugs in GitHub Issues
See Security for security-related concerns

Thank You¶

We appreciate all contributions, whether code, documentation, bug reports, or feature suggestions. You're helping make miniflux-tui-py better for everyone!