============
Contributing
============

Thank you for your interest in contributing to Cocoa!

Getting Started
---------------

1. Fork the repository on GitHub
2. Clone your fork locally
3. Create a feature branch
4. Make your changes
5. Write tests for your features
6. Submit a pull request

Development Environment
-----------------------

Prerequisites
^^^^^^^^^^^^^

- C++20 compiler (GCC 11+, Clang 14+)
- CMake 3.16+
- Kokkos 5.0+ (included with Trilinos 17+)
- Trilinos 17+ (with Tpetra, Belos, Ifpack2, KokkosKernels, Zoltan2)

Setup
^^^^^

.. code-block:: bash

   git clone https://github.com/your-username/cocoa.git
   cd cocoa
   mkdir build && cd build
   cmake .. -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON
   make -j$(nproc)

Code Style
----------

C++ Style
^^^^^^^^^

- Use clang-format with the provided .clang-format file
- Follow the C++ Core Guidelines
- Use descriptive names (avoid abbreviations)
- Document public APIs with Doxygen comments

.. code-block:: cpp

   /**
    * @brief Computes the element mass matrix
    *
    * @param element_id Global element ID
    * @param coords Node coordinates
    * @return 3x3 mass matrix
    */
   Matrix3d computeElementMass(int element_id,
                                const View<double*[2]>& coords);

Naming Conventions
^^^^^^^^^^^^^^^^^^

- Classes: ``PascalCase``
- Functions: ``snake_case``
- Variables: ``snake_case``
- Constants: ``UPPER_SNAKE_CASE``
- Member variables: ``m_name`` (leading m\_ prefix)

Commit Messages
---------------

Follow conventional commit format:

.. code-block:: text

   type(scope): description

   [optional body]

   [optional footer]

Types:

- ``feat``: New feature
- ``fix``: Bug fix
- ``docs``: Documentation
- ``refactor``: Code refactoring
- ``test``: Adding tests
- ``perf``: Performance improvement

Example:

.. code-block:: text

   feat(gwce): add spatially varying tau0 parameter

   Allow tau0 to be specified per-element for improved accuracy
   in complex geometries.

   Closes #123

Pull Request Process
--------------------

1. Ensure all tests pass
2. Update documentation if needed
3. Add tests for new functionality
4. Request review from maintainers
5. Address review feedback
6. Squash commits if requested

Testing Requirements
--------------------

- All new code must have tests
- Tests must pass on all supported platforms
- Code coverage should not decrease

Documentation
-------------

- Document all public APIs
- Update user guide for user-facing changes
- Add examples for new features

Code Review
-----------

All submissions require review. Reviewers will check:

- Correctness
- Performance impact
- Code style compliance
- Test coverage
- Documentation

License
-------

By contributing, you agree that your contributions will be licensed
under the project's license.

Questions?
----------

- Open a GitHub issue
- Contact the maintainers