Skip to content

🚀 Contribution Guide for Rocketdoo

Thank you for your interest in contributing to Rocketdoo! This guide covers everything you need to know to join the project in an organized and effective way.

Table of contents

Branch structure

Rocketdoo follows this branching model:

main              ← stable version, published on PyPI
  └── dev/v2      ← active development for the next version
        └── feature/feature-name   ← your contribution
        └── fix/bug-name
        └── chore/maintenance-task

Golden rule: never work directly on main or dev/v2. Always create a new branch from dev/v2.

Setting up the development environment

Prerequisites

  • Python 3.8 or higher
  • Git
  • Up-to-date pip (pip install --upgrade pip)

1. Fork the repository

On GitHub, click Fork in the top-right corner of the Rocketdoo repository.

2. Clone your fork locally

git clone https://github.com/YOUR_USERNAME/rocketdoo.git
cd rocketdoo

3. Add the original repository as a remote

git remote add upstream https://github.com/OWNER/rocketdoo.git

This lets you sync with changes from the original repo whenever needed:

git fetch upstream
git merge upstream/dev/v2

Installing Rocketdoo in development mode

Create a dedicated virtual environment for development

# From the root of the cloned repo
python -m venv venv-dev

Activate it:

# Linux / macOS
source venv-dev/bin/activate

# Windows
.\venv-dev\Scripts\activate

Install the development branch

Once venv-dev is active, install the specific branch directly from GitHub:

pip install git+https://github.com/OWNER/rocketdoo.git@feature/my-feature

Test the commands in an empty directory

Rocketdoo requires starting from an empty directory, since the first command (rkd scaffold) is what generates the entire project structure. That's why your test environment must be a new, clean folder:

# Create an empty test folder
mkdir my-test && cd my-test

# Run the first Rocketdoo command
rkd scaffold

From there you can continue testing the rest of the commands on the structure generated by scaffold.

Testing your branch without affecting your production install

The recommended approach is to install the branch directly from GitHub into a fresh empty folder, without needing to clone the full repo. This lets you run all Rocketdoo commands in a clean, isolated environment.

pipx is ideal because it installs Rocketdoo in an isolated environment and exposes the commands globally. Using --suffix you can have the production version and the test version running at the same time, without any conflicts:

# Install the test branch with a suffix to tell them apart
pipx install git+https://github.com/OWNER/rocketdoo.git@feature/my-feature --suffix=-test

This gives you two commands available in parallel:

rocketdoo        # ← production version installed from PyPI (untouched)
rocketdoo-test   # ← version from your test branch

To update after pushing new changes to the branch:

pipx reinstall rocketdoo-test

To uninstall when you're done testing:

pipx uninstall rocketdoo-test

Option B — With pip inside a venv (for testing Python imports or scripts)

If you also need to test Python integrations beyond CLI commands:

# Create an empty test folder
mkdir test-rocketdoo && cd test-rocketdoo

# Create and activate a dedicated venv
python -m venv venv-test
source venv-test/bin/activate   # Linux / macOS
# .\venv-test\Scripts\activate  # Windows

# Install the specific branch
pip install git+https://github.com/OWNER/rocketdoo.git@feature/my-feature

To update after pushing changes:

pip install --force-reinstall git+https://github.com/OWNER/rocketdoo.git@feature/my-feature

Private repo: authentication with a token

If the repository is private, you'll need a GitHub personal access token:

pip install git+https://YOUR_TOKEN@github.com/OWNER/rocketdoo.git@feature/my-feature

Summary

Method When to use it
pipx install git+... --suffix=-test Recommended. Test CLI commands without touching the production install
pip install git+... inside a venv Test Python imports or script integrations

Step-by-step workflow

1. Sync with the latest version of dev/v2

git checkout dev/v2
git pull upstream dev/v2

2. Create your working branch

git checkout -b feature/descriptive-name
# Examples:
# git checkout -b feature/multi-model-support
# git checkout -b fix/parser-encoding-error
# git checkout -b chore/update-dependencies

3. Develop and test

Make your changes, run the tests, and make sure everything works:

# Run tests (adjust to the project's test runner)
pytest
# or
python -m pytest tests/

4. Write descriptive commits

We use the Conventional Commits style:

git add .
git commit -m "feat: add support for local models via Ollama"
git commit -m "fix: correct encoding error in long responses"
git commit -m "docs: update README with new usage example"
git commit -m "chore: bump httpx to 0.27"

Commit types: | Type | When to use it | |------|---------------| | feat | New feature | | fix | Bug fix | | docs | Documentation changes | | chore | Maintenance tasks (deps, CI, etc.) | | refactor | Refactoring without behavior change | | test | Adding or fixing tests | | style | Formatting changes (no logic) |

5. Push your branch to your fork

git push origin feature/descriptive-name

6. Open the Pull Request

Open the PR from your fork targeting dev/v2 on the original repository (not main).

Code conventions

  • We follow PEP 8 for Python code style.
  • Use type hints wherever possible.
  • All new code must include basic docstrings.
  • If you add a feature, include at least one test covering it.
  • Avoid introducing new dependencies without prior justification and discussion in the related issue.

How to open a Pull Request

When opening a PR, please include:

  1. Clear description of what changes and why.
  2. Related issue if one exists (e.g. Closes #42).
  3. How to test the changes: commands, test cases, etc.
  4. If applicable, screenshots or output examples.

The PR must target dev/v2, not main. Maintainers will review the code, may request changes, and will merge it once approved.

Reporting bugs or suggesting improvements

Before opening an issue, check if a similar one already exists. If not, open a new one with:

  • Description of the problem or the proposed improvement.
  • Rocketdoo version (pip show rocketdoo).
  • Python version (python --version).
  • Operating system.
  • Steps to reproduce the bug (if applicable).
  • Expected behavior vs. actual behavior.

Questions?

Open a GitHub Discussion or reach out to the project maintainers. Every contribution, no matter how small, is welcome!

This document is part of the official Rocketdoo documentation.