errcraft 0.1.0

# Contributing to errcraft

Thank you for your interest in contributing to errcraft! This document provides guidelines and instructions for contributing.

## 🎯 Ways to Contribute

- **Report bugs**: File detailed bug reports with reproduction steps
- **Suggest features**: Propose new features or enhancements
- **Write code**: Submit pull requests for bug fixes or new features
- **Improve docs**: Enhance documentation, examples, or comments
- **Write tests**: Add test coverage for untested functionality

## 🚀 Getting Started

### Prerequisites

- Rust 1.70.0 or later (MSRV)
- Git
- Familiarity with Rust error handling patterns

### Setup

1. Fork the repository on GitLab
2. Clone your fork:
   ```bash
   git clone https://gitlab.com/YOUR_USERNAME/crates/errcraft.git
   cd errcraft
   ```
3. Create a feature branch:
   ```bash
   git checkout -b feature/my-awesome-feature
   ```

## 📝 Development Workflow

### Building

```bash
# Build with default features
cargo build

# Build with all features
cargo build --all-features

# Build with no default features
cargo build --no-default-features
```

### Testing

```bash
# Run all tests
cargo test --all-features

# Run tests with specific features
cargo test --features serde,markdown

# Run doctests
cargo test --doc
```

### Formatting and Linting

```bash
# Format code
cargo fmt

# Check formatting
cargo fmt -- --check

# Run clippy
cargo clippy --all-targets --all-features -- -D warnings
```

### Documentation

```bash
# Build documentation
cargo doc --all-features --no-deps

# Build and open documentation
cargo doc --all-features --no-deps --open
```

## 📋 Code Guidelines

### Style

- Follow standard Rust formatting (`cargo fmt`)
- Use meaningful variable and function names
- Add documentation comments for public APIs
- Keep functions focused and concise

### Testing

- Write tests for new functionality
- Ensure existing tests pass
- Add doctests for example usage
- Test edge cases and error conditions

### Documentation

- Document all public items with `///` comments
- Include examples in documentation
- Update README.md for significant changes
- Add entries to CHANGELOG.md

### Commits

- Write clear, descriptive commit messages
- Use present tense ("Add feature" not "Added feature")
- Reference issues in commits when applicable
- Keep commits focused and atomic

Example commit message:
```
Add JSON serialization for context layers

Implements serde::Serialize for ContextLayer and adds tests
for JSON output. Closes #42.
```

## 🔍 Pull Request Process

1. **Update your branch**:
   ```bash
   git fetch origin
   git rebase origin/main
   ```

2. **Run the full test suite**:
   ```bash
   cargo test --all-features
   cargo fmt -- --check
   cargo clippy --all-targets --all-features -- -D warnings
   ```

3. **Update documentation**:
   - Add/update docstrings
   - Update README.md if needed
   - Add CHANGELOG.md entry

4. **Create a merge request**:
   - Provide a clear title and description
   - Reference related issues
   - List significant changes
   - Add examples if applicable

5. **Respond to feedback**:
   - Address review comments
   - Make requested changes
   - Update tests as needed

## 🎨 Feature Guidelines

### Before Starting

- Check if an issue exists for your feature
- If not, create one to discuss the proposal
- Get feedback before investing significant time

### Design Principles

- **Ergonomic**: Easy to use, minimal boilerplate
- **Composable**: Work well with existing Rust patterns
- **Performant**: No unnecessary allocations or overhead
- **Safe**: No `unsafe` code without strong justification
- **Compatible**: Maintain MSRV and avoid breaking changes

## 🐛 Bug Reports

Good bug reports include:

- **Clear title**: Summarize the issue
- **Description**: Explain what happened vs. what you expected
- **Reproduction**: Minimal code example that demonstrates the bug
- **Environment**: Rust version, OS, relevant features
- **Logs/Output**: Error messages or unexpected output

Example:

```markdown
## Bug: Context values not displayed with emoji mode

### Description
When using `DisplayOptions::with_emoji(true)`, context values are not
rendered in the output.

### Reproduction
\```rust
let err = ErrFrame::new("Test")
    .context("key", "value");
let opts = DisplayOptions::new().with_emoji(true);
println!("{}", err.to_string_styled(&opts));
\```

### Expected
Should show "📦 Context:" with key=value listed.

### Actual
Only shows error message, no context section.

### Environment
- errcraft: 0.1.0
- Rust: 1.70.0
- OS: Ubuntu 22.04
- Features: default
```

## 📜 License

By contributing, you agree that your contributions will be licensed under the MIT License.

## 💬 Communication

- **Issues**: Use GitLab issues for bug reports and feature requests
- **Discussions**: Use issue comments for questions and discussions
- **Security**: For security issues, see [SECURITY.md](./SECURITY.md)

## 🙏 Recognition

Contributors are recognized in:
- The project README
- Release notes
- Git history

Thank you for making errcraft better! 🎉