======================================== 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: .. code-block:: bash 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`: .. code-block:: bash 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: .. code-block:: bash 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: :ref:`auto-docstrings`. 2.3 Type Hinting ---------------- All function signatures must include **type hints** for arguments and return values. **Example (Required Formatting):** .. code-block:: python 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: .. code-block:: bash 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:** .. code-block:: python 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):** .. code-block:: python def multiply(a: int, b: int) -> int: """Multiplies two integers.""" return a * b # Missing `Returns:` section in docstring. .. _auto-docstrings: 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``: .. code-block:: 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 `_