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 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 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:

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

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