diff --git a/FILE-NAMING-AND-VERSIONING.md b/FILE-NAMING-AND-VERSIONING.md new file mode 100644 index 0000000..cac9945 --- /dev/null +++ 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 diff --git a/KICAD-PROJECT-TEMPLATE.md b/KICAD-PROJECT-TEMPLATE.md index 3521db9..f4dba38 100644 --- 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 diff --git a/README.md b/README.md index 7ba816e..593ab42 100644 --- 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 diff --git a/hardware/bom/README.md b/hardware/bom/README.md index b25b8d6..0f6812c 100644 --- 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 diff --git a/manufacturing/gerbers/README.md b/manufacturing/gerbers/README.md index 4506e33..cb1e779 100644 --- 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 diff --git a/mechanical/stl/README.md b/mechanical/stl/README.md index 962cbdf..52497da 100644 --- 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: