扩展指标

ferro-ta-main/docs/contributing.rst

@@ -0,0 +1,113 @@
+Contributing
+============
+
+Thank you for your interest in contributing to ferro-ta!
+
+This page summarises how to get started. The full details are in
+`CONTRIBUTING.md <https://github.com/pratikbhadane24/ferro-ta/blob/main/CONTRIBUTING.md>`_
+at the repository root.
+
+.. contents::
+   :local:
+   :depth: 2
+
+
+Development setup
+-----------------
+
+Prerequisites: Rust stable toolchain, Python 3.10+, and ``maturin``.
+
+.. code-block:: bash
+
+   git clone https://github.com/pratikbhadane24/ferro-ta.git
+   cd ferro-ta
+   pip install maturin numpy pytest pytest-cov
+   maturin develop --release
+   pytest tests/
+
+
+Git hooks and pre-push checks
+-----------------------------
+
+Install the repository-managed hooks after setting up the environment:
+
+.. code-block:: bash
+
+   make hooks
+
+Run the same push gate manually with:
+
+.. code-block:: bash
+
+   make prepush
+
+You can scope it to selected checks while iterating:
+
+.. code-block:: bash
+
+   make prepush CHECKS="version changelog python_lint"
+
+
+Adding a new indicator
+-----------------------
+
+1. **Rust** — implement the function in the appropriate ``src/<module>/``
+   directory (e.g. ``src/overlap/mod.rs`` and ``src/overlap/sma.rs``).  Follow
+   the existing patterns: slice inputs, ``Vec<f64>`` output, leading NaN for
+   warm-up bars, a ``#[pyfunction]`` decorator, and registration in the
+   module's ``register(m)`` function.
+
+2. **Python** — add a thin wrapper in the matching ``python/ferro_ta/*.py``
+   module using the ``_to_f64`` helper.  Export it in ``__all__``.
+
+3. **Re-export** — add the function to ``python/ferro_ta/__init__.py``'s
+   ``__all__`` list and import block.
+
+4. **Type stub** — add a type annotation to ``python/ferro_ta/__init__.pyi``.
+
+5. **Tests** — add at least one test class in ``tests/test_ferro_ta.py``
+   covering output length, NaN count, and a known-value check.
+
+6. **README** — add a row to the appropriate accuracy table.
+
+
+Code style
+----------
+
+- Rust: ``cargo fmt`` (enforced in CI) and ``cargo clippy -- -D warnings``
+- Python: PEP 8; function names in UPPER_CASE to match TA-Lib convention.
+- All public Python functions should have NumPy-style docstrings.
+
+
+Running tests
+-------------
+
+.. code-block:: bash
+
+   # Python tests
+   pytest tests/ -v
+
+   # Rust format check
+   cargo fmt --check
+
+   # Rust lints
+   cargo clippy --release -- -D warnings
+
+   # Optional: TA-Lib comparison tests (requires ta-lib installed)
+   pytest tests/test_vs_talib.py -v
+
+
+Type checking
+-------------
+
+The package is typed (PEP 561). To run mypy::
+
+   pip install mypy numpy
+   mypy python/ferro_ta --ignore-missing-imports
+
+
+Questions
+---------
+
+Open a GitHub Issue or Discussion. For security vulnerabilities see
+`SECURITY.md <https://github.com/pratikbhadane24/ferro-ta/blob/main/SECURITY.md>`_.