Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
134 lines (92 loc) · 3.82 KB

CONTRIBUTING.md

File metadata and controls

134 lines (92 loc) · 3.82 KB

Contributing to PerceptionMetrics

Thanks for your interest in contributing to PerceptionMetrics! We welcome contributions of all sizes — bug fixes, features, documentation, and improvements.

Please read this guide carefully before getting started.

Code of Conduct

Be respectful, constructive, and kind. Report any unacceptable behavior to one of the maintainers.

Before You Start

  • Read the README.md and project documentation carefully.
  • Run the notebook tutorials first to:
    • Verify your environment setup
    • Understand what the tool does
    • Get familiar with workflows and expected outputs

This helps avoid duplicated work and misunderstandings.

How to Contribute

All contributions follow this workflow:

1. Find or Propose an Issue

  • Check if the bug/feature is already listed in open issues.
  • If not, create a new issue describing:
    • The problem or improvement
    • Proposed approach (if any)
    • Expected impact
    • Relevant examples (code, screenshots, references)

No Pull Requests without an associated issue.

2. Express Interest Before Starting Work

Before starting work — especially for non-trivial issues:

  • Comment on the issue expressing your interest.
  • Briefly describe your proposed approach.
  • Align on expectations, requirements, and scope.

This avoids duplicated efforts and ensures clarity.

3. Development Workflow

The following points depend on your repository permissions.

  • [If you have write permission] Work in a separate branch always:

    • Always work on a separate branch
    • Use descriptive branch names (e.g., issue_123_feature_name)
    • Write clear and meaningful commit messages
    • Do not merge your own PRs

  • [If you have read-only permission] Fork the repository:

    • Fork the repository
    • Work on your fork
    • Submit a Pull Request from your branch

4. Code Quality Requirements

Before opening a PR:

  • Code must be formatted with Black
  • All functions must include Sphinx-style docstrings
  • Code must be properly tested
  • Ensure notebooks and examples still run correctly

5. AI-Assisted Code Policy

We are OK with AI-assisted code, with the following expectations:

  • AI-generated code must be thoroughly tested
  • You must fully understand the code you submit
  • The PR description should clearly explain:
    • What the code does
    • Why it solves the issue
    • Any design decisions made
  • Conversations in issues and PRs are encouraged to be human-to-human
  • Code must be relevant and scoped to the issue it addresses

Submissions that are unclear, untested, or poorly explained may be rejected.

6. Opening a Pull Request

When submitting a PR:

  • Reference the related issue
  • Clearly describe:
    • What was changed
    • Why it was changed
    • How it was tested
  • Add relevant screenshots or examples if helpful
  • Respond to reviewer feedback in a timely manner (within weeks, not months)

A maintainer will review your PR and may request modifications.

Review & Merge Process

  • All changes require review
  • Maintainers will provide feedback
  • Do not merge your own PR (if you have write access)
  • Be proactive and kind during discussions

Contact

If you have any questions, contact the maintainers via email. Please indicate the project name in the subject.

Emails:

d.pascualhe@gmail.com

sergiopaniegoblanco@gmail.com

josemaria.plaza@gmail.com

sakhinetipraveena@gmail.com

We appreciate your time and effort in contributing to PerceptionMetrics! 🚀
⚡