Skip to content

REPOSITORY_STRUCTURE.md

Latest commit

 

History

History
187 lines (157 loc) · 6.22 KB

REPOSITORY_STRUCTURE.md

File metadata and controls

187 lines (157 loc) · 6.22 KB

Ferrous Forge Repository Structure

This document outlines the structure of the Ferrous Forge repository and explains where different types of files belong.

Root Directory

├── Cargo.toml              # Rust package manifest
├── Cargo.lock              # Dependency lock file
├── justfile                # Task runner commands
├── README.md               # Main project documentation
├── VISION.md               # Project vision and philosophy
├── ROADMAP.md              # Development roadmap
├── FEATURES.md             # Feature status tracking
├── CHANGELOG.md            # Version history
├── CONTRIBUTING.md         # Contribution guidelines
├── CODE_OF_CONDUCT.md      # Community standards
├── SECURITY.md             # Security policy
├── CONTRIBUTORS.md         # List of contributors
├── LICENSE-MIT             # MIT license
├── LICENSE-APACHE          # Apache 2.0 license
├── .gitignore              # Git ignore rules
├── .gitattributes          # Git attributes
└── rust-toolchain.toml     # Rust toolchain specification

Source Code

src/
├── main.rs                 # Binary entry point
├── lib.rs                  # Library root
├── cli.rs                  # CLI argument parsing
├── error.rs                # Error types
├── commands/               # Command implementations
│   ├── mod.rs              # Command module root
│   ├── init.rs             # Init command
│   ├── validate.rs         # Validate command
│   ├── fix.rs              # Fix command
│   ├── config.rs           # Config commands
│   ├── safety/             # Safety pipeline commands
│   ├── rust/               # Rust management commands
│   ├── edition/            # Edition management commands
│   └── template/           # Template commands
├── config/                 # Configuration system
│   ├── mod.rs
│   ├── hierarchy/          # Hierarchical config
│   └── locking/            # Config locking
├── validation/             # Validation engine
├── templates/              # Template system
├── git_hooks/              # Git hook scripts
├── rust_version/           # Rust version management
└── ...

Documentation

docs/
├── dev/                    # Development documentation
│   ├── adr/                # Architecture Decision Records
│   └── specs/              # Technical specifications
├── rust-ecosystem-guide.md # New to Rust guide
├── installation.md         # Installation guide
├── configuration.md        # Configuration guide
├── standards.md            # Standards reference
├── integration.md          # Integration guide
├── troubleshooting.md      # Troubleshooting
├── migration.md            # Migration guide
├── USER_STORIES.json       # User stories
└── RUSTDOC-STANDARDS.md    # Documentation standards

Tests

tests/
├── integration_tests.rs    # Integration tests
├── fixtures/               # Test fixtures
└── snapshots/              # Test snapshots

GitHub Configuration

.github/
├── workflows/              # GitHub Actions
│   ├── ci.yml              # CI workflow
│   ├── release.yml         # Release workflow
│   └── update-packages.yml # Package manager updates
├── ISSUE_TEMPLATE/         # Issue templates
│   ├── config.yml          # Issue template config
│   ├── bug_report.md       # Bug report template
│   └── feature_request.md  # Feature request template
├── PULL_REQUEST_TEMPLATE.md # PR template
└── dependabot.yml          # Dependabot configuration

Templates

templates/
├── cli-app/                # CLI application template
├── library/                # Library template
├── wasm/                   # WebAssembly template
├── embedded/               # Embedded template
├── web-service/            # Web service template
├── plugin/                 # Plugin template
└── workspace/              # Workspace template

Packaging

packaging/
├── homebrew/               # Homebrew formula
├── aur/                    # Arch Linux PKGBUILD
├── nix/                    # Nix derivation
└── chocolatey/             # Chocolatey package

Editor Support

editors/
└── vscode/                 # VS Code extension
    ├── package.json
    ├── src/
    └── README.md

CI/CD Artifacts

Generated during CI/CD:

target/
├── debug/                  # Debug builds
├── release/                # Release builds
├── doc/                    # Generated documentation
└── ...

.cleo/                      # CLEO task management
.forge/                     # Forge configuration (test projects)

Where to Add New Files

New Command

  1. Add to src/commands/<name>.rs
  2. Register in src/commands/mod.rs
  3. Add to CLI in src/cli.rs
  4. Add tests in tests/ or inline

New Documentation

  1. Architecture decisions → docs/dev/adr/
  2. Technical specs → docs/dev/specs/
  3. User guides → docs/ root
  4. API docs → /// comments in source

New Template

  1. Create directory in templates/<name>/
  2. Add manifest.toml
  3. Add template files
  4. Register in template registry

New GitHub Workflow

  1. Add to .github/workflows/
  2. Follow naming convention: <purpose>.yml
  3. Update this document

File Naming Conventions

  • Rust files: snake_case.rs
  • Markdown files: UPPERCASE.md for top-level, lowercase.md for docs
  • Directories: lowercase or kebab-case
  • Templates: lowercase with descriptive names
  • Tests: test_<name>.rs or <module>_tests.rs

Important Notes

  1. Never edit README.md directly — it's generated from lib.rs by cargo-rdme
  2. Never edit Cargo.lock manually — managed by Cargo
  3. Always run cargo fmt before committing
  4. Always run cargo clippy and fix warnings
  5. Keep ADRs in docs/dev/adr/ up to date
  6. Update CHANGELOG.md for user-facing changes