# Contributing to EENN
Thank you for your interest in contributing to eenn (Enlightened Equation Neural Network)! This document provides guidelines for contributing to the project.
## Code of Conduct
By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.
## How to Contribute
### Reporting Bugs
Before creating a bug report:
1. **Search existing issues** to avoid duplicates
2. **Use the latest version** to ensure the bug hasn't been fixed
3. **Provide minimal reproduction** with clear steps
When creating a bug report, include:
- **Description**: Clear description of the issue
- **Steps to Reproduce**: Minimal steps to reproduce the behavior
- **Expected Behavior**: What you expected to happen
- **Actual Behavior**: What actually happened
- **Environment**: OS, Rust version, eenn version
- **Code Example**: Minimal code that demonstrates the issue
### Suggesting Features
Feature requests are welcome! Please:
1. **Check the roadmap** ([ROADMAP.md](ROADMAP.md)) to see if it's already planned
2. **Search existing issues** for similar suggestions
3. **Provide context** on why this feature would be valuable
4. **Consider scope** - smaller, focused features are easier to implement
### Pull Requests
#### Before You Start
1. **Discuss major changes** by opening an issue first
2. **Check for existing work** to avoid duplicate effort
3. **Read the codebase** to understand the architecture
#### Development Setup
```bash
# Clone the repository
git clone https://github.com/ciresnave/eenn.git
cd eenn
# Build and test
cargo build
cargo test --all-features
# Run specific tests
cargo test --test basic
cargo test --test node_integration
# Run benchmarks
cargo bench --no-run
```
#### Coding Guidelines
**Rust Style**:
- Follow standard Rust conventions (`rustfmt`)
- Run `cargo fmt` before committing
- Run `cargo clippy -- -D warnings` to catch issues
- Aim for clear, idiomatic Rust code
**Documentation**:
- Add doc comments (`///`) for public APIs
- Include examples in doc comments when helpful
- Update README.md if adding user-facing features
**Testing**:
- Add tests for new functionality
- Ensure all tests pass: `cargo test --all-features`
- Add integration tests for major features
- Consider edge cases and error conditions
**Commits**:
- Write clear, descriptive commit messages
- Use present tense ("Add feature" not "Added feature")
- Reference issue numbers when applicable (#123)
- Keep commits focused on a single change
#### Pull Request Process
1. **Fork the repository** and create a branch from `main`
2. **Make your changes** following the guidelines above
3. **Write tests** for new functionality
4. **Update documentation** as needed
5. **Run tests**: `cargo test --all-features`
6. **Run formatter**: `cargo fmt`
7. **Run linter**: `cargo clippy`
8. **Create a pull request** with:
- Clear title and description
- Reference to related issues
- Summary of changes
- Any breaking changes noted
#### PR Review Process
- Maintainers will review your PR and may request changes
- Address feedback and push updates to your branch
- Once approved, a maintainer will merge your PR
- Your contribution will be included in the next release!
## Development Areas
### High Priority
- **Bug Fixes**: Always welcome!
- **Documentation**: Examples, tutorials, API docs
- **Tests**: Improving test coverage
- **Performance**: Optimization with benchmarks
### Medium Priority
- **New Solvers**: Additional SMT backends
- **Parser Improvements**: Better error messages, syntax extensions
- **Features**: From the roadmap
### Research Areas
- **Neural-Symbolic Integration**: Novel approaches
- **LLM Integration**: Using language models for constraints
- **New Theories**: Extending solver capabilities
## Testing
### Running Tests
```bash
# All tests
cargo test --all-features
# Specific test file
cargo test --test basic
# With output
cargo test -- --nocapture
# Specific test
cargo test test_simple_addition
```
### Test Structure
- `tests/*.rs` - Integration tests
- `src/*/tests.rs` - Unit tests within modules
- `examples/*.rs` - Example programs (should compile)
### Adding Tests
```rust
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_new_feature() {
// Arrange
let input = setup_test_data();
// Act
let result = your_function(input);
// Assert
assert_eq!(result, expected);
}
}
```
## Benchmarking
```bash
# Run all benchmarks
cargo bench --all-features
# Specific benchmark
cargo bench --bench simple_bench
# Save baseline
cargo bench --all-features -- --save-baseline main
# Compare to baseline
cargo bench --all-features -- --baseline main
```
## Documentation
### Building Docs
```bash
# Build documentation
cargo doc --no-deps --all-features
# Open in browser
cargo doc --no-deps --all-features --open
```
### Writing Doc Comments
```rust
/// Solves a constraint problem using the specified backend.
///
/// # Arguments
///
/// * `constraints` - The constraint set to solve
/// * `backend` - The solving backend to use
///
/// # Returns
///
/// A `SolutionResult` containing satisfiability and assignments
///
/// # Examples
///
/// ```
/// use eenn::{solve, SmtBackend};
///
/// let backend = SmtBackend::new();
/// let result = backend.solve(&constraints)?;
/// ```
///
/// # Errors
///
/// Returns an error if the backend fails to solve the constraints.
pub fn solve(&self, constraints: &[Constraint]) -> Result<SolutionResult> {
// Implementation
}
```
## Release Process
(For maintainers)
1. Update version in `Cargo.toml`
2. Update `CHANGELOG.md`
3. Run full test suite: `cargo test --all-features`
4. Create git tag: `git tag -a v0.x.y -m "Release v0.x.y"`
5. Push tag: `git push origin v0.x.y`
6. Publish to crates.io: `cargo publish`
7. Create GitHub release with changelog
## Questions?
- **GitHub Issues**: <https://github.com/ciresnave/eenn/issues>
- **GitHub Discussions**: <https://github.com/ciresnave/eenn/discussions>
## License
By contributing, you agree that your contributions will be licensed under the same terms as the project (MIT OR Apache-2.0).
Thank you for contributing to eenn! 🎉