b4l-project-template/README.md

# B4L KiCad 9 Project Template

Welcome to the **Build4Life (B4L)** KiCad 9 Project Template!  
This repository provides a standardized structure for KiCad 9 hardware projects with proper organization for schematics, PCBs, libraries, documentation, and manufacturing files.

---

## 🚀 Quick Start Guide

### 1. Clone or Download This Template
```bash
# Option A: Clone the repository
git clone https://git.buildfor.life/grabowski/b4l-project-template.git your-project-name
cd your-project-name

# Option B: Download as ZIP and extract
```

### 2. Create Your KiCad 9 Project
1. Open KiCad 9
2. Click **File → New Project**
3. Navigate to the cloned template folder
4. Create your project in the root directory (same level as this README)
5. Name your project (this will create `.kicad_pro`, `.kicad_sch`, and `.kicad_pcb` files)

### 3. Organize Your Files
- Place your main schematic (`.kicad_sch`) and PCB (`.kicad_pcb`) files in the root
- Use the provided folder structure for additional files
- Update the project-specific README files in each folder

### 4. Set Up Version Control
```bash
# Initialize git (if not already done)
git init

# Add your files
git add .
git commit -m "Initial KiCad project setup"

# Add your remote repository
git remote add origin https://your-git-server.com/username/your-project.git
git push -u origin main
```

---

## 📁 KiCad 9 Optimized Folder Structure

```
your-project.kicad_pro     # KiCad 9 project file (root level)
your-project.kicad_sch     # Main schematic file (root level)
your-project.kicad_pcb     # Main PCB file (root level)

kicad/                     # KiCad-specific files
├── libraries/             # Custom KiCad libraries
│   ├── symbols/           # Custom schematic symbols (.kicad_sym)
│   ├── footprints/        # Custom footprints (.pretty folders)
│   └── 3dmodels/          # Custom 3D models (.step, .wrl)
├── schematics/            # Additional/hierarchical schematics
├── gerbers/               # Generated Gerber files
├── plots/                 # PDF plots and prints
└── backups/               # KiCad automatic backups

hardware/                  # Hardware documentation and files
├── bom/                   # Bill of Materials
├── datasheets/            # Component datasheets
├── simulations/           # SPICE simulations
└── assembly/              # Assembly drawings and instructions

manufacturing/             # Production files
├── gerbers/               # Final Gerber files for production
├── drill/                 # Drill files
├── pick-and-place/        # Pick and place files
└── assembly/              # Assembly instructions

mechanical/                # Mechanical design files
├── enclosure/             # Case/enclosure designs
├── cad/                   # 3D CAD files
├── drawings/              # 2D mechanical drawings
└── stl/                   # 3D printable files

firmware/                  # Embedded firmware (if applicable)
├── src/                   # Source code
├── include/               # Header files
└── lib/                   # Libraries

software/                  # PC software and tools
├── gui/                   # GUI applications
└── scripts/               # Automation scripts

docs/                      # Project documentation
├── images/                # Documentation images
├── user-manual/           # User documentation
└── design-notes/          # Design documentation

tests/                     # Testing files
├── hardware/              # Hardware test procedures
├── reports/               # Test reports
└── validation/            # Validation documents

tools/                     # Development tools
ci/                        # Continuous Integration
certs/                     # Certifications and compliance
meta/                      # Project metadata
```

---

## 🔧 KiCad 9 Specific Features

### Project Settings
- Configure your KiCad 9 project settings in the `.kicad_pro` file
- Set up design rules and constraints
- Configure library paths to use the `kicad/libraries/` structure

### Library Management
- Store custom symbols in `kicad/libraries/symbols/`
- Store custom footprints in `kicad/libraries/footprints/`
- Store 3D models in `kicad/libraries/3dmodels/`
- Use relative paths in your project settings

### Version Control Best Practices
- The `.gitignore` file is configured for KiCad projects
- Automatic backups are stored in `kicad/backups/` (excluded from git)
- Generated files (Gerbers, plots) can be committed or ignored based on your workflow

---

## 📋 Workflow Recommendations

### 1. Design Phase
1. Create your schematic in the root `.kicad_sch` file
2. Use hierarchical sheets in `kicad/schematics/` for complex designs
3. Store component datasheets in `hardware/datasheets/`
4. Document design decisions in `docs/design-notes/`

### 2. Layout Phase
1. Design your PCB in the root `.kicad_pcb` file
2. Generate plots and save to `kicad/plots/`
3. Create assembly drawings in `hardware/assembly/`

### 3. Manufacturing Phase
1. Generate final Gerbers to `manufacturing/gerbers/`
2. Create pick-and-place files in `manufacturing/pick-and-place/`
3. Generate BOM in `hardware/bom/`
4. Create assembly instructions in `manufacturing/assembly/`

### 4. Documentation Phase
1. Update all README files in subdirectories
2. Create user manual in `docs/user-manual/`
3. Add project images to `docs/images/`

---

## 🔄 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)
- **CI Auto-Sort**: Use DS_ prefix for datasheets, IMG_ prefix for images
- **Examples**: `my-project_bom_v1.2.0_2024-08-04.csv`, `DS_STM32F401_datasheet_2024-08-11.pdf`

### Initial Setup
```bash
# After creating your KiCad project
git add .
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 "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 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

This template is open source. Choose an appropriate license for your project:
- For hardware: [CERN-OHL-S-2.0](https://ohwr.org/cern_ohl_s_v2.txt)
- For software: [MIT](https://opensource.org/licenses/MIT) or [GPL-3.0](https://www.gnu.org/licenses/gpl-3.0.en.html)

---

## 🤝 Contributing

1. Fork this repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 📡 About Build4Life

**Build4Life** creates long-lasting, open hardware systems.

Website: [https://buildfor.life](https://buildfor.life)