Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
292 lines (210 loc) · 11.4 KB

CONTRIBUTING.md

File metadata and controls

292 lines (210 loc) · 11.4 KB
Raw

Contributing to Picard

Picard and associated plugins and documentation has been a collaborative effort by volunteer contributors from the very start, and contributions continue to be welcome from anyone in the community, as:

Note: Picard and Picard-Plugins code are currently in a state of flux due to development of Picard v3. If you want to contribute by coding, then please discuss this with Phillip Wolfer or Zas before starting.

Please be aware that we try to maintain high quality standards in all these areas, that there is a learning curve to being able to make high-quality contributions, and we consider achieving this to be a team effort with other community members chipping in to help you achieve the quality needed. So please be prepared to welcome constructive criticism on your proposed contributions and consider the effort that is being expended by others to help you in the positive light it is given.

If you want to contribute to the Picard code, then please read-on for details on:

Before starting you might want to ask more experienced contributors for advice about how to get started, and the easiest way for this would be to ask in the MusicBrainz Picard Development chat room on Matrix.

To-Do List

In many cases, people make contributions because of their own experiences - they have had an issue or can see a way that Picard could be improved.

However if you simply would like to contribute and are looking for ideas, then a to-do list of outstanding issues are areas for improvement can be found on the MusicBrainz Jira Tickets system - Picard project.

If you want to pick one of these to work on, make sure that you start with something small as many of these are large-scale, long-term suggestions - if in doubt ask for advice in the chat room so that you don't spend time and effort on something that is too complex or which won't get merged.

Technical Setup

1. Install System Dependencies

gettext (required for translations):

  • Windows: Download from gettext-iconv-windows and add C:\Program Files\gettext-iconv\bin to PATH
  • Linux: sudo apt install gettext
  • macOS: brew install gettext (if not included with Xcode Command Line Tools)

2. Install uv (Recommended)

uv is an extremely fast Python package manager:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Set Up Development Environment

# Clone and enter the repository
git clone https://github.com/metabrainz/picard.git
cd picard

# Create virtual environment
uv venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate.bat  # Windows

# Install all dependencies (main, build, dev)
uv sync

# Build the project
python setup.py build          # Compiles translations and prepares build files
python setup.py build_ext -i   # Builds C extensions in-place for development

# Install in editable mode
uv pip install -e .

4. Run Picard

# After installing in editable mode (recommended)
picard

# Or run directly from source (without installation)
python ./tagger.py

# With debug mode
picard -d
# or
python ./tagger.py -d

5. Run Tests

# With activated virtual environment
pytest -n auto

# Or using uv (if not in activated venv)
uv run pytest -n auto

Development Workflow

Dependency Management

Dependencies are defined in pyproject.toml using modern Python packaging standards:

  • Main dependencies: Runtime requirements for Picard
  • build: Build tools (Babel, PyInstaller, pytest, setuptools)
  • dev: Development tools (ruff, pre-commit, pylint, etc.)
  • plugins: Optional plugin dependencies (aubio, opencc, zstandard)

Important: Never edit requirements files manually. They are auto-generated from pyproject.toml.

Code Quality

Install pre-commit hooks for automatic code quality checks:

pre-commit install

This runs ruff for code style and updates requirements files automatically before each commit.

To manually update requirements after changing pyproject.toml:

pre-commit run pip-compile --all-files

Alternative Setup (Traditional pip)

If you prefer not to use uv:

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-build.txt
pip install -r requirements-dev.txt

# Build and install
python setup.py build          # Compiles translations and prepares build files
python setup.py build_ext -i   # Builds C extensions in-place for development
pip install -e .

Switching Python Versions

With uv (recommended):

# uv automatically manages Python versions
uv venv --python 3.11
uv venv --python 3.12
source .venv/bin/activate
uv sync

With system Python:

# Create separate virtual environments
python3.11 -m venv .venv311
python3.12 -m venv .venv312

# Activate desired version
source .venv311/bin/activate  # or .venv312/bin/activate

# Install dependencies manually
pip install -r requirements.txt -r requirements-build.txt -r requirements-dev.txt

Coding Standards

Style Guidelines

We follow PEP 8 with these exceptions:

  • E501: Line length limit is ~120-130 characters (not 79)

The goal is consistent, readable code within the project.

Code formatting and linting:

# Format code automatically
ruff format

# Check for style and lint issues
ruff check

# Auto-fix issues where possible
ruff check --fix

Docstrings

Use "Google-style" docstrings for functions that aren't immediately obvious.

Picard-Specific Guidelines

  • UI Files: Don't edit picard/ui/ui_*.py directly - these are auto-generated. Use Qt Designer to edit ui/*.ui files, then run python setup.py build_ui to regenerate the Python files
  • Naming: Use snake_case for functions/variables (except pre-generated PyQt code)
  • Internationalization: Use _() for translatable strings and N_() for gettext-noop

Git Workflow

  1. Fork the repository to your account
  2. Create a branch with a meaningful name (e.g., picard-257 or preserve-artwork)
  3. Make changes with good commit messages:
    • Use imperative voice and sentence case
    • Be descriptive but concise
  4. Create a pull request with format: PICARD-257: Allow preserving existing cover-art tags
  5. Reference the issue in the PR description
  6. Keep PRs focused - split unrelated changes into separate PRs
  7. Use git rebase to clean up commits before merging

Documentation

User Documentation

See Picard Documentation project for contributing to the Picard User Guide.

Translations

See po/README.md for translation information.

Audio Metadata Standards

When implementing tag support, aim for compatibility with existing software.

Format Specifications

Tag Mapping References

Additional References