Setup

Thank you for your interest in contributing to this project!

Follow these steps to set up your environment for development.

Prerequisites

This guide assumes you have basic familiarity with Python development, including using pip, virtual environments, and git. These core concepts are beyond the scope of this documentation.

Python Version Requirement

We strongly recommend using Python 3.11 or above for all development work related to recipe-scrapers. This version includes built-in tomllib support, which is essential for the project's configuration handling.

We welcome various types of code contributions to recipe-scrapers, including:

• Bug fixes
• New recipe site scrapers
• Performance improvements
• Feature enhancements
• Test coverage improvements

Fork the Repository

1. Navigate to our repository on GitHub.
2. Click the "Fork" button in the top right corner to create your own copy of the repository.

Clone Your Fork

git clone https://github.com/<your-username>/recipe-scrapers.git
cd recipe-scrapers

Set Upstream Remote

Upstream Remote

Setting the upstream remote allows you to sync changes from the original repository to your fork. This is useful to keep your fork up-to-date with the latest changes.

git remote add upstream https://github.com/hhursev/recipe-scrapers.git

Create a Virtual Environment

It's recommended to use a virtual environment to manage dependencies. You can create one using venv

python -m venv .venv
source .venv/bin/activate  # On Windows: `.venv\Scripts\activate`

Virtual Environment

Remember to activate your virtual environment each time you work on the project:

source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install Dependencies

Install the required dependencies using pip

pip install -e ".[all]"

Our pyproject.toml file lists the installed dependencies and their purposes.

Development Workflow

Create a new branch for your changes:

git checkout -b fix/your-fix-name     # for bug fixes
# or
git checkout -b site/website-name     # for new site scrapers
# or
git checkout -b docs/your-addition    # for docs updates
# or
git checkout -b feature/feature-name  # for new features

After making your changes, commit them:

git add -p  # Review changes before adding them
git commit -m "meaningful commit message"
git push origin your-branch-name

Pre-commit Hooks

The project uses pre-commit hooks to ensure code quality and consistency. These hooks run automatically when you commit changes, handling tasks like:

• Code formatting (black, isort)
• Linting (flake8)
• Type checking
• Other code quality checks

Syncing Your Fork

To keep your fork up-to-date with the original repository, you can fetch and merge changes from the upstream remote:

git fetch upstream
git merge upstream/main

Then create a Pull Request back to the main repository from your fork.

If you have troubles check out Submitting A Pull Request Section.

Submitting a Pull Request

1. Navigate to your fork on GitHub.
2. Click the "New pull request" button.
3. Ensure the base fork is the original repository and the base branch is main.
4. Fill out the pull request template and submit.

Thank you for contributing!

What happens after a PR

When you submit your PR:

1. Our CI suite will run against your code to ensure everything works as expected. You can run the

2. tests locally before submitting:

   python -m unittest
   # or
   unittest-parallel --level test
   

3. Community members and core contributors will review your code. They may:

   • Request changes or improvements
   • Suggest alternative approaches
   • Provide feedback on test coverage
   • Ask for documentation updates

4. Once approved, a core contributor will merge your PR

   • Your contribution will be included in the next release
   • Tackle any follow-up improvements in subsequent PRs

Don't worry if your first PR needs some adjustments - this is normal and part of the collaborative development process!