.. _contributing:

Contributing to glmpynet
========================

First off, thank you for considering contributing to `glmpynet`! We
welcome any help, from reporting a bug to suggesting a new feature. This
project is maintained by volunteers, so your contributions are highly valued.

To ensure a smooth and effective process for everyone, please read
through these guidelines before you start.

How Can I Contribute?
---------------------

There are many ways to contribute, and all of them are appreciated.

1. Reporting Bugs
~~~~~~~~~~~~~~~~~~~~

This is one of the most valuable ways to contribute. If you find a bug,
please `open an issue on our GitHub repository <https://github.com/hrolfrc/glmpynet/issues>`_.
A great bug report is one that can be reproduced. Please include:

* **A clear and descriptive title.**
* **A description of the steps to reproduce the bug.**
* **What you expected to happen vs. what actually happened.**
* **Your environment:** OS, Python version, and package versions.

2. Suggesting Enhancements or New Features
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you have an idea for an improvement, we'd love to hear it. Please
`open an issue <https://github.com/hrolfrc/glmpynet/issues>`_ to start a discussion first.
This allows us to make sure the feature aligns with the project's goals
before any work is done.

3. Improving Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Clear documentation is essential. If you find a typo, think a section is
unclear, or believe something is missing, please open an issue or submit
a pull request with your suggested improvements.

Submitting Code Changes (Pull Requests)
---------------------------------------

We welcome pull requests for bug fixes and approved features. Please ensure
there is an open issue discussing the change before you submit a pull request.

The Development Workflow
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To maintain a stable main branch, all new work must be done on a **feature
branch**.

1.  **Create a Feature Branch:** Before you start working, create a new
    branch from the ``main`` branch. A good branch name is descriptive, like
    ``feat/config-command`` or ``fix/reconciler-bug``.

    .. code-block:: bash

       git checkout -b feat/my-new-feature

2.  **Commit Your Changes:** Make small, logical commits. Each commit should
    represent one self-contained change. All commit messages **must**
    follow the `Conventional Commits <https://www.conventionalcommits.org/>`_
    specification (e.g., ``feat(cli): ...``, ``fix(core): ...``, ``docs(guide): ...``).

Code Quality and Style
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To ensure a consistent codebase, we use standard Python code formatters and
linters. Before committing, please run these tools from the project's root.

* **Black (Formatter):**

  .. code-block:: bash

     pip install black
     black .

* **Ruff (Linter):**

  .. code-block:: bash

     pip install ruff
     ruff check . --fix

Testing
~~~~~~~~~~~~~~~~~~~~

All contributions that change code must be accompanied by tests.

* **New Features:** Must include unit tests that verify correctness.
* **Bug Fixes:** Must include a "regression test" that fails *before* the
  fix is applied and passes *after*.
* To run the full test suite, use `pytest`:

  .. code-block:: bash

     pytest

Submitting the Pull Request
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Once your feature is complete and tested, please follow these steps:

1.  Push your feature branch to GitHub.
2.  Open a Pull Request (PR) against the ``main`` branch.
3.  Provide a clear description of the changes in your PR and link it to the
    relevant issue.
4.  Ensure that all automated checks (like CircleCI) pass.