Add comprehensive file naming and versioning standards

- Add FILE-NAMING-AND-VERSIONING.md with complete Semantic Versioning 2.0.0 and Harvard Data Management file naming conventions - Update README.md with file naming standards and semantic versioning workflow - Update KICAD-PROJECT-TEMPLATE.md with comprehensive file naming examples and git workflow - Update hardware/bom/README.md with standardized BOM file naming conventions - Update manufacturing/gerbers/README.md with production-ready Gerber file naming - Update mechanical/stl/README.md with 3D printing file naming including material suffixes - Implement YYYY-MM-DD date format and hyphen-separated naming throughout - Add versioning strategies for hardware, software, and documentation components - Include git tagging strategy and release management guidelines - Provide comprehensive examples for all file types and directories
2025-08-04 14:46:05 +07:00
parent a0c843204d
commit 3f5b4c7e97
6 changed files with 334 additions and 24 deletions
--- a/FILE-NAMING-AND-VERSIONING.md
+++ b/FILE-NAMING-AND-VERSIONING.md
@@ -0,0 +1,234 @@
+# 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
+```
+
+#### 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
--- a/KICAD-PROJECT-TEMPLATE.md
+++ b/KICAD-PROJECT-TEMPLATE.md
@@ -149,29 +149,55 @@ your-project/
 - [ ] Assembly instructions written
 - [ ] Test procedures documented

-## 🔧 Git Workflow
+## 🔧 Git Workflow and File Naming
+
+This template follows **Semantic Versioning 2.0.0** and **Harvard Data Management file naming conventions**. See [FILE-NAMING-AND-VERSIONING.md](FILE-NAMING-AND-VERSIONING.md) for complete details.
+
+### File Naming Standards
+- **No spaces**: Use hyphens (-) instead of spaces
+- **Date format**: YYYY-MM-DD for chronological sorting
+- **Versioning**: Follow semantic versioning (MAJOR.MINOR.PATCH)
+- **Structure**: `[project-name]_[component-type]_[description]_[version]_[date].extension`
+
+### Examples
+```
+my-project_bom_v1.2.0_2024-08-04.csv
+my-project_gerbers_v1.0.0_2024-08-04.zip
+my-project_user-manual_v1.0.0_2024-08-04.pdf
+my-project_housing-main_v2.0.0.sldprt
+my-project_symbols_mcu_v1.0.0.kicad_sym
+```

 ### Initial Setup
 ```bash
 # After creating KiCad project
 git add .
-git commit -m "Initial KiCad project setup"
+git commit -m "Initial KiCad project setup v1.0.0"
+git tag -a v1.0.0 -m "Initial release - functional prototype"
 git remote add origin https://your-git-server.com/username/your-project.git
 git push -u origin main
+git push --tags
 ```

 ### Development Workflow
 ```bash
 # Regular development cycle
 git add .
-git commit -m "Descriptive commit message"
+git commit -m "Update component values - v1.0.1"
+git tag -a v1.0.1 -m "Bug fix - corrected resistor values"
 git push
+git push --tags

 # For major milestones
-git tag -a v1.0.0 -m "Release version 1.0.0"
+git tag -a v2.0.0 -m "Major PCB redesign with new connector layout"
 git push --tags
 ```

+### Semantic Versioning Strategy
+- **MAJOR**: PCB layout changes, connector changes, mechanical incompatibilities
+- **MINOR**: Component changes, new features, firmware updates  
+- **PATCH**: Documentation updates, BOM corrections, minor fixes
+
 ### Branch Strategy
 - `main`: Stable, tested designs
 - `develop`: Active development
--- a/README.md
+++ b/README.md
@@ -152,33 +152,50 @@ meta/                      # Project metadata

 ---

-## 🔄 Git Workflow
+## 🔄 Git Workflow and Versioning
+
+This project follows **Semantic Versioning 2.0.0** and **Harvard Data Management file naming conventions**. See [FILE-NAMING-AND-VERSIONING.md](FILE-NAMING-AND-VERSIONING.md) for complete details.
+
+### File Naming Standards
+- **No spaces**: Use hyphens (-) instead of spaces
+- **Date format**: YYYY-MM-DD for chronological sorting
+- **Versioning**: Follow semantic versioning (MAJOR.MINOR.PATCH)
+- **Examples**: `my-project_bom_v1.2.0_2024-08-04.csv`

 ### Initial Setup
 ```bash
 # After creating your KiCad project
 git add .
-git commit -m "Add KiCad project files"
+git commit -m "Add KiCad project files v1.0.0"
+git tag -a v1.0.0 -m "Initial release - functional prototype"
 git push
+git push --tags
 ```

 ### Regular Development
 ```bash
 # After making changes
 git add .
-git commit -m "Describe your changes"
+git commit -m "Update component values - v1.0.1"
+git tag -a v1.0.1 -m "Bug fix - corrected resistor values"
 git push
+git push --tags
 ```

 ### Release Preparation
 ```bash
-# Generate manufacturing files
-# Update documentation
-# Tag release
-git tag -a v1.0.0 -m "Release version 1.0.0"
+# Generate manufacturing files with version numbers
+# Update documentation with new version
+# Tag release following semantic versioning
+git tag -a v2.0.0 -m "Major PCB redesign with new connector layout"
 git push --tags
 ```

+### Version Strategy
+- **MAJOR**: PCB layout changes, connector changes, mechanical incompatibilities
+- **MINOR**: Component changes, new features, firmware updates
+- **PATCH**: Documentation updates, BOM corrections, minor fixes
+
 ---

 ## 📝 License
--- a/hardware/bom/README.md
+++ b/hardware/bom/README.md
@@ -63,7 +63,13 @@ U1        | STM32F401  | LQFP-64_10x10mm  | 1   | STM32F401RET6 | Digi-Key | 497
 - **InteractiveHtmlBom**: Creates interactive HTML BOMs

 ## File Naming Convention
- `ProjectName-BOM.csv` - Basic BOM
- `ProjectName-BOM-v1.0.csv` - Versioned BOM
- `ProjectName-BOM-Extended.xlsx` - Detailed BOM with pricing
- `ProjectName-BOM-Assembly.csv` - Assembly-specific BOM
+Following [FILE-NAMING-AND-VERSIONING.md](../../FILE-NAMING-AND-VERSIONING.md) standards:
+- `project-name_bom_v1.0.0_2024-08-04.csv` - Basic BOM
+- `project-name_bom-extended_v1.0.0_2024-08-04.xlsx` - Detailed BOM with pricing
+- `project-name_bom-assembly_v1.0.0_2024-08-04.csv` - Assembly-specific BOM
+- `project-name_bom-production_v2.1.0_2024-08-04.csv` - Production BOM
+
+### Versioning Strategy
+- **MAJOR**: Component changes affecting compatibility
+- **MINOR**: Component value changes, new optional components
+- **PATCH**: Documentation updates, supplier changes
--- a/manufacturing/gerbers/README.md
+++ b/manufacturing/gerbers/README.md
@@ -81,7 +81,18 @@ Create a ZIP file containing:
 - BOM (from `/hardware/bom/`)

 ## File Naming Convention
-Use consistent naming that matches your project:
- `ProjectName-LayerName.gbr`
- `ProjectName-v1.0-Gerbers.zip`
- Include version numbers for tracking
+Following [FILE-NAMING-AND-VERSIONING.md](../../FILE-NAMING-AND-VERSIONING.md) standards:
+- `project-name_gerbers_v1.0.0_2024-08-04.zip` - Complete Gerber package
+- `project-name_gerber-job_v1.0.0_2024-08-04.gbrjob` - Gerber job file
+- `project-name_fabrication-notes_v1.0.0_2024-08-04.txt` - Manufacturing notes
+
+### Individual Layer Files
+- `project-name-f-cu_v1.0.0.gbr` - Front copper
+- `project-name-b-cu_v1.0.0.gbr` - Back copper
+- `project-name-f-silks_v1.0.0.gbr` - Front silkscreen
+- `project-name-edge-cuts_v1.0.0.gbr` - Board outline
+
+### Versioning Strategy
+- **MAJOR**: PCB layout changes, layer stack changes
+- **MINOR**: Component placement changes, routing updates
+- **PATCH**: Silkscreen updates, minor corrections
--- a/mechanical/stl/README.md
+++ b/mechanical/stl/README.md
@@ -42,11 +42,27 @@ stl/
 ```

 ## File Naming Convention
-Use descriptive names that include key specifications:
- `PCB-Mount-Bracket_M3-Holes_v2.1.stl`
- `Sensor-Housing-Top_IP65_ABS.stl`
- `Cable-Gland_PG16_TPU-Flexible.stl`
- `Assembly-Jig_Main-PCB_PLA.stl`
+Following [FILE-NAMING-AND-VERSIONING.md](../../FILE-NAMING-AND-VERSIONING.md) standards:
+- `project-name_pcb-mount-bracket_v2.1.0_petg.stl`
+- `project-name_sensor-housing-top_v1.0.0_abs.stl`
+- `project-name_cable-gland_v1.2.0_tpu.stl`
+- `project-name_assembly-jig_v1.0.0_pla.stl`
+
+### Naming Structure
+`[project-name]_[component-description]_[version]_[material].stl`
+
+### Material Suffixes
+- `_pla` - PLA filament
+- `_petg` - PETG filament
+- `_abs` - ABS filament
+- `_tpu` - TPU flexible filament
+- `_asa` - ASA filament
+- `_pc` - Polycarbonate filament
+
+### Versioning Strategy
+- **MAJOR**: Dimensional changes affecting fit/function
+- **MINOR**: Feature additions, improvements
+- **PATCH**: Print setting optimizations, minor corrections

 ## Print Settings Documentation
 Include recommended print settings for each component: