test/CONTRIBUTING.rst

Contributing to the StarlingX Test Repo

This document outlines the contribution guidelines for the starlingx/test repository.

StarlingX Test is an open-source project, and we welcome contributions from the community. This guide explains the requirements for code contributions, pre-commit checks, and documentation compliance.

1. Setting Up Your Development Environment

1.1 Clone the Repository

First, clone the repository and set up your environment:

git clone https://opendev.org/starlingx/test.git
cd test

1.2 Install Dependencies

Ensure you have Python 3.11 installed, then install dependencies using `pipenv`:

pip install --user pipenv
pipenv install --dev

1.3 Enable Pre-Commit Hooks

Pre-commit hooks are required to ensure code formatting and docstring compliance:

pre-commit install

Once installed, pre-commit will automatically run on every commit.

2. Code Contribution Guidelines

2.1 Code Style

• Python code must be formatted with black and isort.
• Line length should not exceed 200 characters.
• Use f-strings instead of % formatting or .format().

2.2 Docstring Standards

All docstrings should follow the Google Python Style Guide and must be formatted consistently to pass pre-commit checks.

• Google-style docstrings are required for all functions and classes, with the following exceptions:

  • Module-level docstrings are not required or enforced by pre-commit hooks.

    However, they are recommended for utility scripts and config files to clarify their intended use for other developers.

  • __init__ methods are allowed to have docstrings but are not required.

    If a docstring is present, it should describe the purpose of the constructor and any initialization logic.

The pre-commit hooks automatically enforce PEP 257 and Google-style docstrings using pydocstyle, pydoclint, and interrogate.

For auto-generating docstrings that align with these standards, see: auto-docstrings.

2.3 Type Hinting

All function signatures must include type hints for arguments and return values.

Example (Required Formatting):

def add(a: int, b: int) -> int:
    """
    Adds two numbers.

    Args:
        a (int): The first number.
        b (int): The second number.

    Returns:
        int: The sum of `a` and `b`.
    """
    return a + b

3. Pre-Commit Hooks & Linting

This repository uses pre-commit hooks to enforce formatting, linting, and docstring compliance.

3.1 Installed Pre-Commit Hooks

The following tools are run automatically on every commit:

• black: Enforces PEP 8-compliant code formatting.
• isort: Ensures import statements are correctly ordered.
• flake8: Static code analysis and linting.
• pydocstyle: Enforces PEP 257 and Google-style docstring formatting.
• pydoclint: Ensures function signatures and docstrings match.
• interrogate: Ensures all functions and classes have docstrings.

3.2 Running Pre-Commit Hooks Manually

You can run pre-commit checks manually before committing:

pre-commit run --all-files

4. Handling Return Types in Docstrings & Type Hints

4.1 Why Are Return Types Required in Both Docstrings and Type Hints?

We enforce return type hints (e.g., -> type) and docstring return types (e.g., Returns: section) to ensure consistency.

Why is this required?

• Ensures clarity in documentation.
• Helps enforce consistency across the project.
• Required by pre-commit hooks (pydocstyle, pydoclint, interrogate).

4.2 Example of Correct Formatting

Correct Example:

def multiply(a: int, b: int) -> int:
    """
    Multiplies two integers.

    Args:
        a (int): The first integer.
        b (int): The second integer.

    Returns:
        int: The product of `a` and `b`.
    """
    return a * b

Incorrect Example (Missing `Returns:` section):

def multiply(a: int, b: int) -> int:
    """Multiplies two integers."""
    return a * b  # Missing `Returns:` section in docstring.

5. Auto-Generating Docstrings in VSCode & PyCharm

To simplify docstring compliance, you can use IDE plugins.

5.1 VSCode: Auto-Generating Docstrings

1. Install the [Python Docstring Generator](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring).

2. Configure VSCode to generate Google-style docstrings that align with pre-commit checks.

   Add the following settings to your settings.json:

   {
       "autoDocstring.docstringFormat": "google",
       "autoDocstring.includeName": true,
       "autoDocstring.includeExtendedSummary": true,
       "autoDocstring.guessTypes": true,
       "autoDocstring.startOnNewLine": true,
       "autoDocstring.quoteStyle": "\"\"\"",
       "autoDocstring.generateDocstringOnEnter": true
   }

3. Save the file and restart VSCode.

5.2 PyCharm: Auto-Generating Docstrings

1. Open PyCharm.
2. Go to File → Settings → Tools → Python Integrated Tools.
3. Find the Docstring format dropdown and select Google.
4. Click Apply and OK.

6. References

• OpenStack Contributor Guide
• OpenStack Individual Contributor License Agreement (ICLA)
• OpenDev Developer Documentation
• StarlingX Contributor Guidelines
• StarlingX Code Submission Guide
• How to Contribute to StarlingX (YouTube)
• OpenStack Git Commit Message Guidelines
• Google Python Style Guide
• PEP 257 (Docstring Conventions)
• PEP 484 (Type Hints)
• PEP 498 (f-Strings)
• pydocstyle Documentation
• pydoclint Documentation
• interrogate Documentation
• pre-commit
• black
• isort
• flake8
• AutoDocstring for VSCode
• VSCode: Auto-Generating Docstrings
• PyCharm: Creating Documentation Comments