Contributing to mkdocs-rsoxs¶

Thank you for your interest in contributing to mkdocs-rsoxs!

Development Setup¶

1. Fork and clone the repository:

git clone https://github.com/als-rsoxs/mkdocs-rsoxs.git
cd mkdocs-rsoxs

1. Install dependencies using uv:

uv sync --group dev

1. Install prek hooks:

prek install

Making Changes¶

1. Create a new branch for your feature or bugfix:

git checkout -b feature/your-feature-name

1. Make your changes and ensure tests pass:

uv run pytest

1. Ensure code quality:

uv run ruff check .
uv run ruff format .
uv run ty check

1. Commit your changes using conventional commits:

git commit -m "feat: add new feature"

Commit Message Format¶

We use Conventional Commits. Here are some examples:

• feat: add new feature - A new feature
• fix: resolve bug in X - A bug fix
• docs: update README - Documentation changes
• refactor: simplify code - Code refactoring
• test: add tests for X - Adding tests
• chore: update dependencies - Maintenance tasks

Pull Request Process¶

1. Update documentation if needed
2. Add tests for new functionality
3. Ensure all tests pass
4. Submit a pull request with a clear description

Dependency Updates¶

This project uses Renovate for automated dependency updates. Renovate will automatically open pull requests when new versions are available for:

• GitHub Actions
• Python dependencies (via pyproject.toml)
• uv.lock lockfile

To activate it:

1. Go to github.com/apps/renovate and click Install
2. Choose your GitHub account or organization
3. Under Repository access, select this repository (or all repositories)
4. Click Install & Authorize
5. Renovate will open an onboarding pull request titled Configure Renovate — merge it to activate
6. Renovate will now open PRs automatically when new dependency versions are available

The renovate.json at the root of this project is pre-configured to manage:

• GitHub Actions workflow dependencies
• Python dependencies (via pyproject.toml)

Code Style¶

• We use Ruff for linting and formatting
• We use ty for type checking
• All code should be properly typed
• Write docstrings for public functions and classes