Skip to content

Submitting Pull Request (PR) Guidelines

These guidelines outline how to submit a high-quality Pull Request (PR) to DeFFcode.

Before You Start

First time contributing to DeFFcode?

 

Create a Working Branch

Start by cloning your fork and creating a feature branch from the latest master:

Keep your fork up to date

Ensure your fork’s master branch is synced with the upstream repository before starting.

# Clone your fork (replace with your username)
git clone https://github.com/{YOUR_USERNAME}/DeFFcode.git
cd DeFFcode

# Sync latest changes
git pull

# Create a new branch
git checkout -b feature/your-branch-name

Work on this branch and push changes as usual.

 

PR Submission Checklist

1. Open an Issue First

  • Start by creating an issue using the proposal template
  • This helps align your work with project goals and avoids duplicate effort

2. Open a Draft PR Early

  • Create a draft PR from the beginning of your work
  • Add:
    • A clear and descriptive title
    • Summary of what the PR fixes/adds/improves
    • Screenshots or outputs (if applicable)
  • For bug fixes:
    • Include a failing test case that your fix resolves
  • Ensure all CI checks pass
  • Mark as Ready for Review once complete

3. Test, Format & Lint Locally

  • Run tests and ensure everything passes
  • Format and lint your code before committing
  • See Testing & Linting section below

4. Write Clear Commit Messages

  • Keep messages concise and meaningful
  • Link issues using keywords like resolves #123
  • Use git commit --amend to refine commits when needed

5. Perform Integrity Checks

Duplicate PRs will be rejected

  • Check for existing related PRs/issues
  • Ensure your changes align with DeFFcode’s design and goals
  • By contributing, you agree your code will be licensed under the Apache 2.0 License ➶

Tip

Learn more about linking PRs to issues here ➶

  • Link your PR to the relevant issue
  • This helps track progress and avoid duplication

 

Testing, Formatting & Linting

All PRs must pass testing and code quality checks.

Requirements

Python 3.10+ required

Install dependencies:

# Install OpenCV (if not already installed)
pip install opencv-python

# Install remaining dependencies
pip install --upgrade ruff pytest vidgear[core]

Test Dataset Setup

Download required test data:

chmod +x scripts/bash/prepare_dataset.sh
./scripts/bash/prepare_dataset.sh

sh scripts/bash/prepare_dataset.sh

Run Tests

From the project root:

pytest -sv

 

Formatting & Linting (Ruff)

DeFFcode uses Ruff for both linting and formatting.

Lint Code

# Check for issues
ruff check {path}

# Auto-fix issues
ruff check --fix {path}

Format Code

# Apply formatting
ruff format {path}

# Check formatting only
ruff format --check {path}

These checks run in CI—running them locally saves time during review.

 

Frequently Asked Questions

Q1. Why is my PR taking time to be reviewed?

After your PR is merged

  • You can delete your branch safely
  • Changes are first merged into dev, then into master during release
  • Active contributors may receive faster reviews over time

PRs are reviewed by maintainers based on priority and availability. You may be asked to make changes before approval.

Q2. Can I submit a large PR?

  • Yes—but ensure changes are focused and related
  • For major changes:
    • Open an issue first for discussion
    • Large, unrelated changes should be split into smaller PRs

This helps speed up review and increases the chances of acceptance.

Thanks for contributing to DeFFcode 🚀