b4l-project-template/FILE-NAMING-AND-VERSIONING.md

# File Naming and Versioning Standards

This document defines the file naming conventions and versioning standards for the KiCad 9 project template, following Semantic Versioning 2.0.0 and Harvard Data Management file naming conventions.

## 📋 File Naming Conventions

Based on [Harvard Data Management File Naming Conventions](https://datamanagement.hms.harvard.edu/plan-design/file-naming-conventions) with project-specific adaptations.

### General Rules
- **No spaces**: Use hyphens (-) instead of spaces
- **Date format**: YYYY-MM-DD for chronological sorting
- **Case sensitivity**: Use consistent case (prefer lowercase with hyphens)
- **Special characters**: Avoid special characters except hyphens and underscores
- **Length**: Keep filenames under 255 characters
- **Descriptive**: Use meaningful, descriptive names

### File Naming Structure
```
[project-name]_[component-type]_[description]_[version]_[date].extension
```

### Examples by File Type

#### KiCad Files
```
my-project.kicad_pro                    # Main project file
my-project.kicad_sch                    # Main schematic
my-project.kicad_pcb                    # Main PCB layout
my-project_power-supply.kicad_sch       # Hierarchical sheet
my-project_mcu-core.kicad_sch           # Hierarchical sheet
```

#### Library Files
```
my-project_symbols_mcu_v1.2.0.kicad_sym
my-project_symbols_connectors_v1.0.0.kicad_sym
my-project_footprints_custom.pretty/
my-project_3dmodels_enclosure_v2.1.0.step
```

#### Documentation Files
```
my-project_user-manual_v1.0.0_2024-08-04.pdf
my-project_assembly-guide_v2.1.0_2024-08-04.md
my-project_bom_v1.3.0_2024-08-04.csv
my-project_schematic-plot_v1.0.0_2024-08-04.pdf
```

#### Datasheets and Images (CI Auto-Sort)
For automatic organization by CI bots, use these prefixes:
```
DS_STM32F401_datasheet_v1.0.0_2024-08-04.pdf      # Auto-moves to docs/datasheets/
DS_LM358_operational-amplifier_2024-08-04.pdf     # Auto-moves to docs/datasheets/
IMG_pcb-layout_top-view_v1.0.0_2024-08-04.png     # Auto-moves to docs/images/
IMG_assembly-photo_step-3_2024-08-04.jpg          # Auto-moves to docs/images/
IMG_schematic-block-diagram_v2.1.0_2024-08-04.svg # Auto-moves to docs/images/
```

**Prefix Rules:**
- **DS_**: Datasheets - automatically moved to `docs/datasheets/`
- **IMG_**: Images, diagrams, photos - automatically moved to `docs/images/`

#### Manufacturing Files
```
my-project_gerbers_v1.0.0_2024-08-04.zip
my-project_drill-file_v1.0.0_2024-08-04.drl
my-project_pick-and-place_top_v1.0.0_2024-08-04.csv
my-project_pick-and-place_bottom_v1.0.0_2024-08-04.csv
```

#### Mechanical Files
```
my-project_housing-main_v2.0.0.sldprt
my-project_pcb-bracket_v1.1.0.sldprt
my-project_assembly-drawing_v1.0.0_2024-08-04.pdf
my-project_housing-top_3d-print_v1.2.0.stl
```

#### Test and Validation Files
```
my-project_test-report_functional_v1.0.0_2024-08-04.pdf
my-project_validation-data_emc_v1.0.0_2024-08-04.xlsx
my-project_test-procedure_assembly_v2.0.0_2024-08-04.md
```

## 🏷️ Semantic Versioning 2.0.0

Following [Semantic Versioning 2.0.0](https://semver.org/) specification.

### Version Format
```
MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
```

### Version Components
- **MAJOR**: Incompatible changes (e.g., PCB layout changes requiring new manufacturing)
- **MINOR**: Backward-compatible functionality additions (e.g., new features, component changes)
- **PATCH**: Backward-compatible bug fixes (e.g., documentation updates, minor corrections)
- **PRERELEASE**: Optional pre-release identifiers (alpha, beta, rc)
- **BUILD**: Optional build metadata

### Examples
```
1.0.0          # Initial release
1.0.1          # Bug fix (documentation update)
1.1.0          # New feature (added sensor interface)
2.0.0          # Breaking change (PCB layout redesign)
2.1.0-alpha.1  # Pre-release version
2.1.0+20240804 # Build metadata
```

### Project Versioning Strategy

#### Hardware Versions
- **MAJOR**: PCB layout changes, connector changes, mechanical incompatibilities
- **MINOR**: Component value changes, new optional features, firmware updates
- **PATCH**: Documentation updates, BOM corrections, assembly improvements

#### Software/Firmware Versions
- **MAJOR**: API changes, protocol changes, incompatible updates
- **MINOR**: New features, performance improvements
- **PATCH**: Bug fixes, security patches

#### Documentation Versions
- **MAJOR**: Complete restructure, format changes
- **MINOR**: New sections, significant content additions
- **PATCH**: Corrections, clarifications, minor updates

## 📁 Directory-Specific Naming

### KiCad Libraries
```
kicad/libraries/symbols/
├── project-name_symbols_mcu_v1.0.0.kicad_sym
├── project-name_symbols_power_v1.1.0.kicad_sym
└── project-name_symbols_connectors_v2.0.0.kicad_sym

kicad/libraries/footprints/
├── project-name_footprints_custom.pretty/
├── project-name_footprints_connectors.pretty/
└── project-name_footprints_mechanical.pretty/

kicad/libraries/3dmodels/
├── connectors/
│   ├── usb-c-receptacle_v1.0.0.step
│   └── header-2x10-2.54mm_v1.0.0.step
└── enclosure/
    ├── main-housing-top_v2.1.0.step
    └── main-housing-bottom_v2.1.0.step
```

### Manufacturing Files
```
manufacturing/gerbers/
├── project-name_gerbers_v1.0.0_2024-08-04.zip
├── project-name_gerber-job_v1.0.0_2024-08-04.gbrjob
└── project-name_fabrication-notes_v1.0.0_2024-08-04.txt

manufacturing/drill/
├── project-name_drill-pth_v1.0.0_2024-08-04.drl
├── project-name_drill-npth_v1.0.0_2024-08-04.drl
└── project-name_drill-report_v1.0.0_2024-08-04.txt

manufacturing/pick-and-place/
├── project-name_pnp-top_v1.0.0_2024-08-04.csv
├── project-name_pnp-bottom_v1.0.0_2024-08-04.csv
└── project-name_assembly-notes_v1.0.0_2024-08-04.txt
```

### Documentation Files
```
docs/design-notes/
├── project-name_requirements_v1.0.0_2024-08-04.md
├── project-name_architecture_v1.1.0_2024-08-04.md
├── project-name_component-selection_v2.0.0_2024-08-04.md
└── design-reviews/
    ├── project-name_review-001_schematic_2024-08-04.md
    └── project-name_review-002_layout_2024-08-04.md

docs/user-manual/
├── project-name_user-manual_v1.0.0_2024-08-04.pdf
├── project-name_quick-start_v1.0.0_2024-08-04.md
└── project-name_troubleshooting_v1.1.0_2024-08-04.md
```

### Mechanical Files
```
mechanical/cad/
├── main-assembly/
│   ├── project-name_main-assembly_v1.0.0.sldasm
│   └── project-name_system-layout_v1.0.0.slddrw
├── pcb-mount/
│   ├── project-name_pcb-bracket_v1.2.0.sldprt
│   └── project-name_standoffs_v1.0.0.sldprt
└── enclosure/
    ├── project-name_housing-main_v2.0.0.sldprt
    └── project-name_housing-cover_v2.0.0.sldprt

mechanical/stl/
├── enclosure-parts/
│   ├── project-name_housing-top_v2.0.0_pla.stl
│   └── project-name_housing-bottom_v2.0.0_pla.stl
└── mounting-hardware/
    ├── project-name_pcb-bracket_v1.2.0_petg.stl
    └── project-name_cable-clamp_v1.0.0_tpu.stl
```

## 🏷️ Git Tagging Strategy

### Release Tags
Follow semantic versioning for git tags:
```bash
git tag -a v1.0.0 -m "Initial release - functional prototype"
git tag -a v1.1.0 -m "Added sensor interface and improved power management"
git tag -a v2.0.0 -m "Major PCB redesign with new connector layout"
```

### Pre-release Tags
```bash
git tag -a v2.0.0-alpha.1 -m "Alpha release for testing new PCB layout"
git tag -a v2.0.0-beta.1 -m "Beta release with manufacturing files"
git tag -a v2.0.0-rc.1 -m "Release candidate - final testing"
```

## 📝 Implementation Guidelines

### File Creation Checklist
- [ ] Use hyphens instead of spaces
- [ ] Include version number for versioned files
- [ ] Use YYYY-MM-DD date format when applicable
- [ ] Follow project naming convention
- [ ] Keep filename length reasonable
- [ ] Use descriptive, meaningful names

### Version Update Process
1. **Determine version increment** (MAJOR.MINOR.PATCH)
2. **Update all related files** with new version
3. **Update documentation** with version changes
4. **Commit changes** with version in commit message
5. **Tag release** with semantic version
6. **Update changelog** with version history

### Documentation Requirements
- Maintain version history in CHANGELOG.md
- Document breaking changes clearly
- Include migration guides for major versions
- Reference version numbers in all documentation
- Keep version consistency across all project files