# Contributing to Datalab CLI
Thank you for your interest in contributing to Datalab CLI! This document provides guidelines and instructions for contributing.
## Code of Conduct
Please be respectful and constructive in all interactions. We're all here to build great software together.
## Getting Started
### Prerequisites
- Rust 1.70 or later
- Git
### Development Setup
1. Fork and clone the repository:
```bash
git clone https://github.com/YOUR_USERNAME/datalab-cli
cd datalab-cli
```
2. Build the project:
```bash
cargo build
```
3. Run tests:
```bash
cargo test
```
4. Run the CLI locally:
```bash
cargo run -- convert document.pdf
```
## Development Workflow
### Code Style
We use `rustfmt` and `clippy` to maintain consistent code style:
```bash
# Format code
cargo fmt
# Check formatting
cargo fmt --check
# Run lints
cargo clippy
# Run lints with warnings as errors
cargo clippy -- -D warnings
```
Please ensure all code passes these checks before submitting a PR.
### Running Tests
```bash
# Run all tests
cargo test
# Run tests with output
cargo test -- --nocapture
# Run a specific test
cargo test test_name
```
### Building Documentation
```bash
# Build MkDocs documentation
cd documentation
pip install -r requirements.txt
mkdocs serve
```
## Making Changes
### Branching Strategy
- Create feature branches from `main`
- Use descriptive branch names: `feature/add-xyz`, `fix/issue-123`, `docs/update-readme`
### Commit Messages
Write clear, concise commit messages:
```
Add support for PDF/A output format
- Add --pdf-a flag to convert command
- Update output handling for PDF/A compliance
- Add tests for new functionality
```
### Pull Request Process
1. **Create a PR** against the `main` branch
2. **Fill out the PR template** with all relevant information
3. **Ensure CI passes** - all tests and lints must pass
4. **Request review** from maintainers
5. **Address feedback** and update your PR as needed
6. **Squash commits** if requested before merge
### PR Checklist
- [ ] Code follows the project's style guidelines
- [ ] Tests added for new functionality
- [ ] Documentation updated if needed
- [ ] CHANGELOG.md updated for user-facing changes
- [ ] All CI checks pass
## Reporting Issues
### Bug Reports
When reporting bugs, please include:
- Datalab CLI version (`datalab --version`)
- Operating system and version
- Steps to reproduce the issue
- Expected behavior
- Actual behavior
- Any error messages or logs
### Feature Requests
For feature requests, please describe:
- The problem you're trying to solve
- Your proposed solution
- Any alternatives you've considered
- Additional context or examples
## Architecture Overview
```
src/
├── main.rs # CLI entry point and argument parsing
├── lib.rs # Library exports
├── client.rs # HTTP client for Datalab API
├── cache.rs # Local file-based caching
├── error.rs # Error types and handling
├── output.rs # Progress and output formatting
└── commands/ # Command implementations
├── convert.rs
├── extract.rs
├── segment.rs
├── fill.rs
├── track_changes.rs
├── create_document.rs
├── extract_score.rs
├── files.rs
├── workflows.rs
└── cache.rs
```
### Key Concepts
- **Commands** are implemented in `src/commands/` with clap derive macros
- **API client** handles authentication, request building, and polling
- **Cache** stores responses keyed by file hash + endpoint + parameters
- **Output** handles JSON output to stdout and progress to stderr
## Getting Help
- Open a [GitHub issue](https://github.com/dipankar/datalab-cli/issues) for bugs or feature requests
- Check existing issues before creating new ones
- For questions, use [GitHub Discussions](https://github.com/dipankar/datalab-cli/discussions)
## License
By contributing, you agree that your contributions will be licensed under the MIT License.
---
Thank you for contributing!