# Contributing to nxCypher

Thank you for your interest in contributing to nxCypher! This document provides guidelines and information for contributors.

## Reporting Bugs

If you find a bug, please open a [GitHub Issue](../../issues/new?template=bug_report.md) with:

- A clear description of the problem
- A minimal Cypher query that reproduces the issue
- The expected vs. actual result
- Your Python and nxCypher versions

## Proposing Features

Feature requests are welcome! Please open a [GitHub Issue](../../issues/new?template=feature_request.md) describing:

- The Cypher feature or function you'd like to see
- A use case for why it's needed
- Example queries showing expected behavior

## Development Setup

nxCypher uses [uv](https://docs.astral.sh/uv/) for dependency management.

```bash
# Clone the repository
git clone https://github.com/<owner>/nxcypher.git
cd nxcypher

# Install dependencies (creates .venv automatically)
uv sync

# Run the test suite
uv run pytest nxcypher/ -v

# Run the linter
uv run ruff check nxcypher/
```

## Code Style

- We use [ruff](https://docs.astral.sh/ruff/) for linting (config in `.ruff.toml`)
- Follow existing code patterns in the codebase
- Add tests for any new functionality
- Keep changes focused — one feature or fix per pull request

## Developer Certificate of Origin (DCO)

This project uses a [Developer Certificate of Origin](DCO) (DCO). All contributions must include a `Signed-off-by` line in the commit message, certifying that you wrote or have the right to submit the code.

To sign off your commits, use the `-s` flag:

```bash
git commit -s -m "Add support for new_function()"
```

This adds a line like:

```
Signed-off-by: Your Name <your.email@example.com>
```

If you forget to sign off, you can amend your last commit:

```bash
git commit --amend -s --no-edit
```

## Pull Request Process

1. **Fork** the repository and create a feature branch from `master`
2. **Write tests** for your changes — all new features need test coverage
3. **Run the full test suite** and ensure all tests pass:
   ```bash
   uv run pytest nxcypher/ -v
   ```
4. **Run the linter** and fix any issues:
   ```bash
   uv run ruff check nxcypher/
   ```
5. **Sign off** all commits with DCO (see above)
6. **Open a pull request** against `master` with a clear description of your changes

## Testing

- Tests are in `nxcypher/test_*.py` files
- Use `pytest` with NetworkX graph fixtures
- Follow the existing test patterns (see `test_queries.py` for examples)
- Aim for both positive tests (correct behavior) and edge cases

## License

By contributing, you agree that your contributions will be licensed under the [Apache License 2.0](LICENSE).
