Development Guide¶

Getting Help¶

We use GitHub issues for tracking bugs and feature requests and have limited bandwidth to address them. If you need anything, I ask you to please follow our templates for opening issues or discussions.

Git Workflow¶

This project follows a Git Flow branching model. All development happens on the develop branch — never commit directly to master.

---
config:
  gitGraph:
    mainBranchName: master
---
gitGraph
    commit id: "v0.14.0"
    branch develop
    checkout develop
    commit id: "start dev"
    branch feature/173
    checkout feature/173
    commit id: "FEATURE-#173"
    commit id: "PEP8-#173"
    checkout develop
    merge feature/173 id: "PR #183"
    branch bug/143
    checkout bug/143
    commit id: "BUG-#143"
    checkout develop
    merge bug/143 id: "PR #159"
    branch docs/95
    checkout docs/95
    commit id: "DOCS-#95"
    checkout develop
    merge docs/95 id: "PR develop"
    checkout master
    merge develop id: "Release v0.15.0" tag: "v0.15.0"

Branch Naming¶

All branches must be created from develop and follow the pattern:

Type	Pattern	Example	When to use
Feature	`feature/<ISSUE-NUMBER>`	`feature/173`	New functionality
Bug Fix	`bug/<ISSUE-NUMBER>`	`bug/143`	Fixing a reported bug
Documentation	`docs/<ISSUE-NUMBER>`	`docs/95`	Documentation-only changes
Release	`release/<VERSION>`	`release/1.0.0`	Preparing a new release

Creating a Branch¶

git checkout develop
git pull origin develop
git checkout -b feature/123

Commit Style¶

Every commit must follow the format:

<emoji> <TYPE>-#<ISSUE-NUMBER>: <Description>

Icon	Type	Description
⚙️	FEATURE	New feature
📝	PEP8	Formatting fixes following PEP8
📌	ISSUE	Reference to issue
🪲	BUG	Bug fix
📘	DOCS	Documentation changes
📦	PyPI	PyPI releases
❤️️	TEST	Automated tests
⬆️	CI/CD	Changes in continuous integration/delivery
⚠️	SECURITY	Security improvements

Examples¶

⚙️ FEATURE-#173: Add GitHub Actions deployer with PyGithub SDK
🪲 BUG-#143: Fix retry=0 causing zero execution attempts
📘 DOCS-#173: Add documentation section and references to README
📝 PEP8-#173: Apply ruff format to CLI commands
❤️ TEST-#173: Add tests for all Lambda variant deployers
📌 ISSUE-#173: Resolve merge conflict with develop
📦 PyPI: Update version to 0.15.0.dev2

Pull Requests¶

Target Branch¶

Feature/bug/docs branches → open PR against develop
Release branches → open PR against master

PR Guidelines¶

When opening a PR, fill out the provided template:

Description — Summarize the changes and link the related issue
Type of change — Check the appropriate box (bug fix, feature, breaking change, docs)
Checklist — Confirm code quality, tests, and documentation

Before Opening a PR¶

[ ] Code follows the project style guidelines
[ ] Self-review completed
[ ] Tests added/updated and passing locally
[ ] No new warnings introduced
[ ] Documentation updated (if applicable)

Code Quality¶

Linting & Formatting¶

This project uses ruff for formatting and flake8 + pylint for linting.

# Format code
ruff format .

# Check linting
flake8
pylint dotflow/

Tests¶

Run the test suite with:

pytest

Project Structure¶

dotflow/
├── dotflow/          # Main library
│   ├── abc/          # Abstract base classes
│   ├── cli/          # CLI commands
│   ├── cloud/        # Cloud deployers
│   ├── core/         # Core pipeline engine
│   ├── providers/    # Storage/queue providers
│   └── utils/        # Utility functions
├── tests/            # Test suite
├── docs/             # MkDocs documentation source
├── docs_src/         # Documentation examples
├── examples/         # Usage examples
└── scripts/          # Build/utility scripts

Development Setup¶

# Clone the repository
git clone https://github.com/dotflow-io/dotflow.git
cd dotflow

# Install dependencies with Poetry
poetry install --all-extras

# Activate the virtual environment
poetry shell

Summary¶

Branch from develop using the naming convention
Commit with emoji + type + issue number
Open a PR against develop (or master for releases)
Pass all checks — linting, tests, and self-review
Wait for code review and approval before merging