Developer Guide
First off, thank you for considering contributing to ez-animate
! We're excited to have your help. This guide provides all the necessary information to get your development environment set up and to start contributing.
Prerequisites
Before you begin, please make sure you have the following installed on your system:
- Git: For version control.
- Python: Version 3.8 or newer.
- uv: The fast project and environment manager. If you don't have it, you can install it with:
pip install uv
Step-by-Step Setup
This will guide you from cloning the repository to having a fully functional local development setup.
1. Fork and Clone the Repository
First, fork the repository on GitHub. Then, clone your fork to your local machine:
git clone https://github.com/SantiagoEnriqueGA/ez-animate.git
cd ez-animate
2. Create and Activate the Virtual Environment
We use uv
to manage our virtual environment. This keeps project dependencies isolated from your global Python installation.
# Create the virtual environment in a .venv directory
uv venv
# Activate it
# On macOS/Linux:
source .venv/bin/activate
# On Windows (PowerShell):
.venv\Scripts\Activate.ps1
# On Windows (CMD):
.venv\Scripts\activate.bat
You'll know the environment is active when you see (.venv)
at the beginning of your command prompt.
3. Install Dependencies
Install the project in "editable" mode along with all development dependencies (for testing, linting, and documentation).
# This command installs ez-animate and all its dependencies for development
uv pip install -e .[dev]
Why this command?
-e .
: Installs the package in editable mode. This means any changes you make to the source code in thesrc/
directory will be immediately available in your environment without needing to reinstall.[dev]
: This is an "extra" defined in ourpyproject.toml
. It installs the optional groups of dependencies needed for running tests, checking code style, and building the documentation.
You are now ready to start developing!
Running Tests
We use pytest
for testing. High-quality, passing tests are required for any contribution to be merged.
To run the entire test suite:
uv run pytest
To run tests in a specific file:
uv run pytest tests/test_animator.py
To run tests with code coverage:
uv run pytest --cov=src/ez_animate --cov-report=term-missing
Code Style and Linting
To maintain a consistent and high-quality codebase, we use Ruff for code formatting and linting. Before submitting any code, please run this tool.
Ruff (Linter and Formatter)
Ruff is an extremely fast linter that helps catch common errors and style issues.
# Check for any issues
uv run ruff check .
# Automatically fix any fixable issues
uv run ruff check . --fix
The CI/CD pipeline will fail if your code is not properly formatted, so it's best to run this before committing.
Building the Documentation
Our documentation is built with MkDocs. This allows you to preview your documentation changes locally before they are published.
To start the live-reloading local server:
uv run mkdocs serve
Now, open your web browser and navigate to http://127.0.0.1:8000. The server will automatically rebuild the documentation and refresh your browser whenever you save a change in the docs/
directory.
Submitting Your Changes
- Create a New Branch: Start from the
main
branch and create a descriptive branch name for your feature or bugfix.git checkout main git pull origin main git checkout -b feature/my-cool-animation
- Make Your Changes: Write your code and the corresponding tests.
- Test and Lint: Run the tests and linters to ensure everything is correct.
uv run pytest uv run ruff check . --fix uv run ruff format .
- Commit Your Code: Use a descriptive commit message following the Conventional Commits standard.
git add . git commit -m "feat: Add new FadeIn animation effect"
- Push to Your Fork:
git push origin feature/my-cool-animation
- Open a Pull Request: Go to the
ez-animate
repository on GitHub and open a Pull Request from your fork's branch to themain
branch. Provide a clear description of your changes.
Dependency Management
The project's dependencies are defined in pyproject.toml
.
- Core dependencies are listed under
[project.dependencies]
. These are required for the package to run. - Development dependencies are listed under
[project.optional-dependencies]
.
If you need to add or remove a dependency, please update pyproject.toml
accordingly and mention it in your Pull Request.