Skip to content

Contributing to STS

Getting Started

Prerequisites

  • Python 3.9 or later
  • uv

Setup

Clone repository:

git clone git@gitlab.com:rh-kernel-stqe/sts.git
cd sts

Install dependencies:

uv sync  # Creates .venv with all development dependencies

Configure pre-commit/prek:

prek install

Development Workflow

Create branch

git checkout main && git pull --rebase origin main
git checkout -b branch-name

Make changes

Following our code standards

Test changes

# Note: These steps are running in pre-commit checks and CI pipelines.
uv run ruff check                              # Lint
uv run ruff format                             # Format
uv run basedpyright                            # Type check
uv run pytest                                  # Run unit tests

Commit changes and submit merge request

  • Clear description of changes
  • Conventional Commits format (recommended but not required)
  • Reference to any related issues
  • Add attributions for AI-tools contributions, like Linux kernel docs

Merge Request Requirements

  • All CI checks pass
  • One maintainer approval required
  • Test coverage for new functionality
  • Updated documentation for API changes

See Writing Tests Guide for detailed testing instructions.

Code Standards

Requirements

Aspect Requirement
Python version 3.9+
Line length 120 characters maximum
String quotes Single quotes preferred
Type hints Required for all functions
Docstrings Google style convention

Quality Tools

  • ruff - Fast Python linting and formatting
  • basedpyright - Static type checking
  • pytest - Testing framework
  • prek - pre-commit checks

Key Rules

  • No unused imports or variables
  • No bare except: clauses
  • No mutable default arguments
  • Proper async/await patterns
  • PEP 8 naming conventions

Testing

  • Unit tests recommended where suitable
  • Use pytest framework
  • Coverage reports generated automatically
  • Focus on descriptive test names

Documentation Guidelines

  • Documentation is built using mkdocs with the Material theme
  • API documentation is automatically generated from docstrings
  • Developers are encouraged to add their own documentation:
    • Add usage examples and best practices
    • Include troubleshooting tips
    • Provide architecture diagrams or flowcharts
    • Share implementation notes or design decisions
    • Document common pitfalls or gotchas
    • Add links to related documentation or resources

Enhancing Documentation

While docstrings provide the core API documentation, you can enhance the documentation by adding additional content before or after the auto-generated sections. For example:

# My Module

Some introductory text explaining the module's purpose and key concepts.

## Usage Tips

Here are some best practices for using this module effectively...

## API Reference

::: sts.my_module

## Implementation Notes

Additional details about the implementation, design decisions, etc...

## Common Patterns

Examples of common usage patterns and their explanations...

Using MkDocs Plugins

We encourage the use of MkDocs plugins to enhance documentation. The Material theme supports many useful plugins that can improve documentation quality and readability.

Browse the MkDocs Material Plugins page for a complete list of available plugins and their features.

To use a plugin:

  1. Add it to the project's [docs] dependencies
  2. Configure it in mkdocs.yml
  3. Use it in your documentation

For example, to add a Mermaid diagram:

```mermaid
graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];

graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];

Build and Preview

Make sure the docs dependency group is installed:

uv sync --group docs

To build the documentation locally, run:

uv run mkdocs build

Build and preview documentation locally using:

uv run mkdocs serve

Visit http://127.0.0.1:8000 to see your changes.

Getting Help

Support Channels

Before Asking

  1. Check existing issues
  2. Review documentation and examples
  3. Test with minimal reproduction case

Effective Reports

  • Environment details (OS, Python version, STS version)
  • Minimal reproduction case
  • Expected vs actual behavior
  • Full error messages and stack traces
  • Steps to reproduce