# Contributing to penmanship
Thank you for your interest in contributing to `penmanship`! This document provides guidelines for contributing to the project.
## Code of Conduct
This project adheres to the Contributor Covenant [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
## How to Contribute
### Reporting Bugs
If you find a bug, please create an issue with:
- A clear, descriptive title
- Steps to reproduce the problem
- Expected vs actual behavior
- Your environment (OS, Rust version, `penmanship` version)
- Any relevant error messages or logs
### Suggesting Enhancements
Enhancement suggestions are welcome! Please create an issue describing:
- The motivation for the enhancement
- A clear description of the proposed functionality
- Any potential implementation considerations
### Pull Requests
1. **Fork and Clone**: Fork the repository and clone it locally
2. **Create a Branch**: Create a feature branch from `main`
3. **Make Changes**: Follow the project's coding standards (see below)
4. **Test**: Ensure all tests pass with `cargo test`
5. **Lint**: Run `cargo clippy` and address any warnings
6. **Commit**: Write clear, descriptive commit messages
7. **Push**: Push your branch to your fork
8. **Open a PR**: Submit a pull request to the `main` branch
## Development Setup
```bash
# Clone your fork
git clone https://github.com/YOUR-USERNAME/penmanship.git
cd penmanship
# Build the project
cargo build
# Run tests
cargo test
# Run clippy
cargo clippy
# Generate documentation
cargo doc --open
```
## Coding Standards
This project maintains strict code quality standards:
### Required Practices
- **No unsafe code**: The codebase forbids `unsafe` code
- **Comprehensive documentation**: All items (public and private) must be documented
- Include `# Errors`, `# Panics`, and `# Safety` sections where applicable
- **One item per file**: Generally, place one public item (struct, enum, or trait) per file
- File names should match the item name
- Include a comment if violating this guideline
### Code Organization
- **Category modules**: Follow the existing pattern with feature flags
- **Static mappings**: Use `phf::phf_map!` for compile-time perfect hash maps
- **Error handling**: Library functions should never panic
- **Testing**: Add tests for new functionality in `#[cfg(test)]` modules
### Whitelist .gitignore
This project uses a whitelist approach to version control. Only explicitly allowed files are tracked. When adding new files:
- Source code: Automatically included if in `src/**/*.rs`
- Documentation: Update `.gitignore` if adding new docs
- Scripts: Update `.gitignore` if adding scripts
## Adding a New Category
To add a new character category:
1. Create `src/categories/categoryname.rs` with a static `phf_map!`
2. Add a feature flag to `Cargo.toml`
3. Add the module to `src/categories/mod.rs`
4. Add lookup logic to `src/lookup.rs`
5. Gate code with `#[cfg(feature = "categoryname")]`
6. Update documentation (README.md, lib.rs, etc.)
7. Add comprehensive tests
## Testing
- Write unit tests for new functionality
- Test all mappings from your category
- Test case sensitivity where relevant
- Ensure tests pass with `cargo test --all-features`
- Test with `--no-default-features` for minimal builds
- Document test panic expectations
## Documentation
- Update README.md for user-facing changes
- Add rustdoc comments for all public APIs
- Include examples in documentation where helpful
- Run `cargo doc --open` to preview documentation
## Dependencies
- Keep dependencies minimal and well-vetted
- Discuss new dependencies before adding them
- Use feature flags to keep dependencies optional when possible
- Prefer compile-time dependencies over runtime dependencies
## Questions?
If you have questions about contributing, feel free to:
- Open an issue for discussion
- Check existing issues and pull requests for context
Thank you for contributing to `penmanship`!