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
This commit is contained in:
234
FILE-NAMING-AND-VERSIONING.md
Normal file
234
FILE-NAMING-AND-VERSIONING.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user