CONTRIBUTING.rst

Overview

The [CONTRIBUTING.rst](/projects/286/67321) file serves as the official guide for contributing to the *pytest* project. It provides comprehensive instructions and best practices for various contribution activities such as submitting bug reports, feature requests, writing code (including bug fixes and new features), preparing pull requests, writing tests, and joining the development team.

This document aims to ensure a smooth, consistent, and efficient contribution workflow for both new and experienced contributors by outlining the project's expectations, coding standards, and collaboration mechanisms.

Detailed Sections and Usage

This file is structured as a reStructuredText document with multiple thematic sections. Each section focuses on a specific aspect of contributing to pytest.

1. Feature Requests and Feedback

• Purpose: Encourages users to share ideas, suggestions, and feedback.

• How to contribute: Submit issues on GitHub with a narrow scope and detailed explanations.

• Usage Example:
  Visit https://github.com/pytest-dev/pytest/issues and open a new issue describing your feature request.

2. Report Bugs

• Purpose: Guides users on how to properly report bugs.

• Key instructions:

  • Include OS and version.

  • Include Python interpreter version, installed libraries, pytest version.

  • Provide detailed reproduction steps.

  • Optionally, include a failing test case (xfail).

• Usage Example:
  Open an issue in the GitHub issue tracker with detailed environment info and reproduction steps.

3. Fix Bugs

• Purpose: Helps contributors find bugs to fix and how to engage.

• Important points:

  • Look for issues labeled as bugs or "good first issue".

  • Communicate intent by commenting on the issue.

  • Check plugin issue trackers for bugs as well.

4. Implement Features

• Purpose: Guidelines for implementing new features.

• How to proceed:

  • Look for enhancement issues.

  • Discuss with developers before implementation.

5. Write Documentation

• Purpose: Encourages improvements to documentation including translations, docstrings, blog posts.

• Building docs: Use tox -e docs to build documentation locally.

• Docstring standards: Uses Sphinx docstring format with examples provided.

**Docstring Example:**

def my_function(arg: ArgType) -> Foo:
    """Do important stuff.

    :param short_arg: An argument which determines stuff.
    :param long_arg: A long explanation which spans multiple lines.
    :returns: The result.
    :raises ValueError: Detailed info when this can happen.

    .. versionadded:: 6.0
    """

6. Submitting Plugins to pytest-dev

• Purpose: Explains how to submit plugins to the pytest-dev organization.

• Requirements:

  • PyPI presence with pytest- prefix.

  • tox configuration for tests.

  • README, LICENSE, issue tracker, changelog.

• Process:

  • Submit a discussion topic on GitHub.

  • Repository transfer procedure described.

  • Maintainers and release rights explained.

7. Preparing Pull Requests

• Short version:

  • Fork, fetch tags, install pre-commit, follow PEP-8.

  • Run tests with tox -e linting,py39.

  • Write changelog entry.

  • Add yourself to AUTHORS.

• Long version: Detailed step-by-step instructions for cloning, branching, running tests, committing, and submitting PRs.

• Tools:

  • pre-commit for style checks.

  • tox for running tests in virtual environments.

• Example commands:

git clone [email protected]:YOUR_GITHUB_USERNAME/pytest.git
git fetch --tags https://github.com/pytest-dev/pytest
git checkout -b your-branch-name main
pip install --user pre-commit
pre-commit install
pip install tox
tox -e linting,py39
git commit -a -m "Fix issue #123"
git push -u

8. Writing Tests

• Purpose: Advice on writing tests for pytest or plugins.

• Recommended approach: Use the pytester fixture for black-box testing.

• Usage Examples:

def test_true_assertion(pytester):
    pytester.makepyfile("def test_foo(): assert True")
    result = pytester.runpytest()
    result.assert_outcomes(passed=1, failed=0)

def test_false_assertion(pytester):
    pytester.makepyfile("def test_foo(): assert False")
    result = pytester.runpytest()
    result.stdout.fnmatch_lines(["*assert False*", "*1 failed*"])

• Test file selection: Place new tests in files related to the feature/bug area.

9. Joining the Development Team

• How to join: Successfully merged pull requests without extra review work grant commit access.

• Process: Same pull-request review process applies to all contributors, including committers.

10. Merge/Squash Guidelines

• Merge strategies:

  • Squash: For miscellaneous commits or related commits without individual value.

  • Merge: For commits with distinct topics or valuable individual history.

• Backport PRs: Always squash to preserve author attribution.

• Examples provided to guide decision-making.

11. Backporting Bug Fixes

• Purpose: How to include bug fixes in patch releases.

• Process:

  • Fix bug on main branch first.

  • Use labels or manual cherry-pick to backport.

• Responsibility: Usually core developers or merge maintainers.

• Backport PRs: Should always be squashed.

12. Handling Stale Issues/PRs

• Definition: Issues/PRs inactive for a long time after requests for changes.

• Reasons: Busy contributors, lost interest, forgotten.

• Closing policy:

  • Questions/information issues: close after 14 days inactivity.

  • Proposals: close after 6 months inactivity.

  • PRs: ping after 1 month, possibly close.

• Closing messages: Polite, appreciative, encouraging reopening.

13. Closing Issues

• When PR fixes issue: Use closes #issue_number in PR description/commits.

• User-error issues: Explain politely and encourage closure.

• Unresponsive users: Follow stale policy.

Implementation Details

• The file is a structured text document using reStructuredText syntax, designed for rendering as project documentation.

• Hyperlinks and references use standard RST and Sphinx conventions.

• Code blocks and examples illustrate expected usage and formats.

• No executable code or algorithms are present.

Interactions with Other Parts of the System

• GitHub Integration: Guides contributors to use GitHub issues, pull requests, labels, and discussions.

• Testing Framework: Uses tox and pytest for running tests and linting.

• Documentation System: References Sphinx for documentation building and docstring formats.

• Plugin Ecosystem: Explains plugin submission to pytest-dev organization repositories.

• Development Workflow: Interacts with repository branches, tags, and changelog files.

• Pre-commit Hooks: Integration with pre-commit tool for style enforcement.

The file acts as the centralized resource to align contributors with the project's development standards and workflows, ensuring consistency and quality.

Visual Diagram: Contribution Workflow Flowchart

flowchart TD
    A[Start: Want to contribute?] --> B{Type of Contribution?}
    B -->|Bug Report| C[Submit Issue with Details]
    B -->|Feature Request| D[Submit Issue: Narrow Scope]
    B -->|Code Fix/Feature| E[Fork & Clone Repo]
    E --> F[Create Branch]
    F --> G[Install pre-commit & tox]
    G --> H[Write Code & Tests]
    H --> I[Run Tests with tox]
    I --> J{Tests Pass?}
    J -->|No| H
    J -->|Yes| K[Write Changelog Entry]
    K --> L[Add to AUTHORS if needed]
    L --> M[Commit & Push]
    M --> N[Open Pull Request]
    N --> O{PR Review}
    O -->|Request Changes| H
    O -->|Approved| P[Merge/Squash PR]
    P --> Q[Backport if needed]
    Q --> R[Contribution Complete]
    C & D --> R

Summary

The [CONTRIBUTING.rst](/projects/286/67321) file is an essential guide that standardizes and facilitates contributions to pytest by clearly defining processes for bug reporting, feature requests, coding, testing, documentation, plugin submission, PR preparation, and project maintenance. It supports community engagement and helps maintain the quality and sustainability of the project through well-defined workflows and communication protocols.