# Contributing to rust-ai-driven-development-pipeline-template
Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to this project.
## Development Setup
1. **Fork and clone the repository**
```bash
git clone https://github.com/YOUR-USERNAME/rust-ai-driven-development-pipeline-template.git
cd rust-ai-driven-development-pipeline-template
```
2. **Install Rust**
Install Rust using rustup (if not already installed):
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
3. **Install development tools**
```bash
rustup component add rustfmt clippy
cargo install rust-script
```
4. **Install pre-commit hooks** (optional but recommended)
```bash
pip install pre-commit
pre-commit install
```
5. **Build the project**
```bash
cargo build
```
## Development Workflow
1. **Create a feature branch**
```bash
git checkout -b feature/my-feature
```
2. **Make your changes**
- Write code following the project's style guidelines
- Add tests for any new functionality
- Update documentation as needed
3. **Run quality checks**
```bash
cargo fmt
cargo clippy --all-targets --all-features
rust-script scripts/check-file-size.rs
cargo fmt --check && cargo clippy --all-targets --all-features && rust-script scripts/check-file-size.rs
```
4. **Run tests**
```bash
cargo test
cargo test --verbose
cargo test --doc
cargo test test_name
```
5. **Add a changelog fragment**
For any user-facing changes, create a changelog fragment:
```bash
touch changelog.d/$(date +%Y%m%d_%H%M%S)_my_change.md
```
Edit the file to document your changes:
```markdown
### Added
- Description of new feature
### Fixed
- Description of bug fix
```
**Why fragments?** This prevents merge conflicts in CHANGELOG.md when multiple PRs are open simultaneously.
6. **Commit your changes**
```bash
git add .
git commit -m "feat: add new feature"
```
Pre-commit hooks will automatically run and check your code.
7. **Push and create a Pull Request**
```bash
git push origin feature/my-feature
```
Then create a Pull Request on GitHub.
## Code Style Guidelines
This project uses:
- **rustfmt** for code formatting
- **Clippy** for linting with pedantic and nursery lints enabled
- **cargo test** for testing
### Code Standards
- Follow Rust idioms and best practices
- Use documentation comments (`///`) for all public APIs
- Write tests for all new functionality
- Keep functions focused and reasonably sized
- Keep files under 1000 lines
- Use meaningful variable and function names
### Terminology: it is a links network, never a graph
The structure this project stores its tokens in is a **links network**: links
whose sources and targets are themselves links. The word *graph* is not used
for it, and CI rejects it.
The distinction is load-bearing rather than stylistic. In a graph you have
vertices joined by edges, and the edge is a relationship *between* two things
that are not themselves edges. In a links network there is no separate kind of
thing to be a vertex: every link is addressable, and a link can be the source
or target of another link. A "point" is just a link whose source and target are
itself. Calling it a graph invites reasoning that quietly does not hold — that
edges are anonymous, that they cannot be referenced, that vertices are a
distinct population to be counted separately.
- **Write:** "links network", or plain **"network"** where the context already
makes it clear ("the network is parsed once per process").
- **Do not write:** "graph", "the doublets graph", "semantic graph",
`parse_graph()`, `let graph = ...`.
This applies to **identifiers as well as prose** — variable, function, type and
test names — and to documentation in **every human language**, not only
English.
Other people's names for their own things are fine, and the check allows them:
GraphQL, Git's *object graph*, a build system's *dependency graph*, and
ordinary words that merely contain the letters (paragraph, lexicographic,
geographic). If you hit a genuine case the check does not know about, add it to
`ALLOWED_PHRASES` in `scripts/check-terminology.rs` **with a reason** — the
list is deliberately narrow.
This file, `CHANGELOG.md` and `changelog.d/` may name the word freely, because
their job is to state the rule and to record that the wording changed. They are
the only places that may. Everywhere else — source, `README.md`, the rest of
`docs/`, workflows — is checked, so do not reach for the changelog as a way to
say it elsewhere.
Run it locally the way CI does:
```bash
rust-script scripts/check-terminology.rs
```
`dev/log/` and captured third-party text under `docs/case-studies/*/raw/` are
excluded as records rather than as wording to fix — editing them would falsify
what was written at the time — and `ui/dist/` is a built bundle.
### Documentation Format
Use Rust documentation comments:
```rust
/// Brief description of the function.
///
/// Longer description if needed.
///
/// # Arguments
///
/// * `arg1` - Description of arg1
/// * `arg2` - Description of arg2
///
/// # Returns
///
/// Description of return value
///
/// # Errors
///
/// Description of when errors are returned
///
/// # Examples
///
/// ```
/// use my_package::example_function;
/// let result = example_function(1, 2);
/// assert_eq!(result, 3);
/// ```
pub fn example_function(arg1: i32, arg2: i32) -> i32 {
arg1 + arg2
}
```
## Testing Guidelines
- Write tests for all new features
- Maintain or improve test coverage
- Use descriptive test names
- Organize tests in modules when appropriate
- Use `#[cfg(test)]` for test-only code
Example test structure:
```rust
#[cfg(test)]
mod tests {
use super::*;
mod my_feature_tests {
use super::*;
#[test]
fn test_basic_functionality() {
assert_eq!(my_function(), expected_result);
}
#[test]
fn test_edge_case() {
assert_eq!(my_function(edge_case_input), expected_result);
}
}
}
```
## Pull Request Process
1. Ensure all tests pass locally
2. Update documentation if needed
3. Add a changelog fragment (see step 5 in Development Workflow)
4. Ensure the PR description clearly describes the changes
5. Link any related issues in the PR description
6. Wait for CI checks to pass
7. Address any review feedback
## Changelog Management
This project uses a fragment-based changelog system similar to [Scriv](https://scriv.readthedocs.io/) (Python) and [Changesets](https://github.com/changesets/changesets) (JavaScript).
### Creating a Fragment
```bash
# Create a new fragment with timestamp
touch changelog.d/$(date +%Y%m%d_%H%M%S)_description.md
```
### Fragment Categories
Use these categories in your fragments:
- **Added**: New features
- **Changed**: Changes to existing functionality
- **Deprecated**: Features that will be removed in future
- **Removed**: Features that were removed
- **Fixed**: Bug fixes
- **Security**: Security-related changes
### During Release
Fragments are automatically collected into CHANGELOG.md during the release process. The release workflow:
1. Collects all fragments
2. Updates CHANGELOG.md with the new version entry
3. Removes processed fragment files
4. Bumps the version in Cargo.toml
5. Creates a git tag and GitHub release
## Project Structure
```
.
├── .github/workflows/ # GitHub Actions CI/CD
├── changelog.d/ # Changelog fragments
│ ├── README.md # Fragment instructions
│ └── *.md # Individual changelog fragments
├── examples/ # Usage examples
├── scripts/ # Rust scripts (via rust-script)
├── src/
│ ├── lib.rs # Library entry point
│ └── main.rs # Binary entry point
├── tests/ # Integration tests
├── .gitignore # Git ignore patterns
├── .pre-commit-config.yaml # Pre-commit hooks
├── Cargo.toml # Project configuration
├── CHANGELOG.md # Project changelog
├── CONTRIBUTING.md # This file
├── LICENSE # Unlicense (public domain)
└── README.md # Project README
```
## Release Process
This project uses semantic versioning (MAJOR.MINOR.PATCH):
- **MAJOR**: Breaking changes
- **MINOR**: New features (backward compatible)
- **PATCH**: Bug fixes (backward compatible)
Releases are managed through GitHub releases. To trigger a release:
1. Manually trigger the release workflow with a version bump type
2. Or: Update the version in Cargo.toml and push to main
## Getting Help
- Open an issue for bugs or feature requests
- Use discussions for questions and general help
- Check existing issues and PRs before creating new ones
## Code of Conduct
- Be respectful and inclusive
- Provide constructive feedback
- Focus on what is best for the community
- Show empathy towards other community members
Thank you for contributing!