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

We welcome contributions to the TACO Format project! This page provides guidelines for contributing to the project.

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

1. **Fork the repository** on GitLab
2. **Clone your fork**:

   .. code-block:: bash

       git clone https://gitlab.com/YOUR_USERNAME/taco.git
       cd taco

3. **Create a development environment**:

   .. code-block:: bash

       # Install development dependencies
       pip install -e ".[dev]"

4. **Create a branch** for your feature:

   .. code-block:: bash

       git checkout -b feature-name

5. **Make your changes** and add tests
6. **Run the tests** to ensure everything works:

   .. code-block:: bash

       # Run Rust tests
       cargo test
       
       # Run Python tests
       pytest

7. **Submit a merge request** on GitLab

Development Guidelines
----------------------

Code Style
~~~~~~~~~~

- **Rust code** should follow Rust style conventions and pass `cargo clippy` checks
- **Python code** should follow PEP 8 guidelines
- **Documentation** should be written in reStructuredText

Adding Features
~~~~~~~~~~~~~~~

1. **Start with tests**: Write tests that define how your feature should work
2. **Implement the feature**: Make it work!
3. **Document it**: Add documentation for your feature
4. **Update examples**: If applicable, add examples using your feature

Adding Documentation
~~~~~~~~~~~~~~~~~~~~

Documentation is written in reStructuredText and built with Sphinx:

1. Add or update documentation in the `docs/` directory
2. Build the documentation to test your changes:

   .. code-block:: bash

       cd docs
       make html
       
3. Open `_build/html/index.html` in your browser to view the result

Running Benchmarks
------------------

Performance is important to TACO Format. You can run benchmarks to ensure your changes don't negatively impact performance:

.. code-block:: bash

    cd docs
    python format_comparison.py --atoms 1000 --frames 100 --output benchmark_results

This will produce benchmark results comparing TACO with other formats.

Continuous Integration
----------------------

Our GitLab CI pipeline runs tests and checks for each merge request. It:

1. Runs tests on multiple platforms
2. Checks code style with clippy
3. Ensures documentation builds correctly
4. Runs security audits with cargo audit

Release Process
---------------

1. Update version numbers in:
   - `Cargo.toml`
   - `pyproject.toml`
   - Documentation
2. Update the changelog (CHANGELOG.md)
3. Create a tag for the new version
4. Push to GitLab to trigger the release pipeline

The release pipeline will:
1. Run all tests
2. Build documentation
3. Publish to crates.io and PyPI (these are manual steps in the pipeline)