breedr/RELEASE_NOTES_v0.4.0.md

# BREEDR v0.4.0 Release Notes

**Release Date:** March 9, 2026  
**Branch:** `docs/clean-schema-and-roadmap-update`  
**Focus:** Clean Database Schema & Documentation Overhaul

---

## 🆕 What's New

### Clean Database Architecture

We've completely overhauled the database design for simplicity and correctness:

- **✅ NO MORE MIGRATIONS** - Fresh init creates correct schema automatically
- **✅ Removed weight/height columns** - Never implemented, now gone
- **✅ Added litter_id column** - Proper linking of puppies to litters
- **✅ Parents table approach** - NO sire/dam columns in dogs table
- **✅ Normalized relationships** - Sire/dam stored in separate parents table

### Why This Matters

The old schema had:
- Migration scripts trying to fix schema issues
- `sire_id` and `dam_id` columns causing "no such column" errors
- Complex migration logic that could fail

 The new schema:
- ✅ Clean initialization - always correct
- ✅ Normalized design - proper relationships
- ✅ Simple maintenance - no migration tracking
- ✅ Better logging - see exactly what's happening

---

## 🛠️ Technical Changes

### Database

**Removed:**
- `dogs.weight` column (never implemented)
- `dogs.height` column (never implemented) 
- `dogs.sire_id` column (moved to parents table)
- `dogs.dam_id` column (moved to parents table)
- `server/db/migrations.js` (no more migrations)

**Added:**
- `dogs.litter_id` column with foreign key to litters
- `parents` table for sire/dam relationships
- Clean `server/db/init.js` as single source of truth

### API Changes

**server/routes/dogs.js:**
- Fixed parent handling - properly uses parents table
- Added detailed logging for relationship creation
- Removed schema detection logic
- Cleaner error messages

**server/index.js:**
- Removed migrations import and execution
- Simplified startup - just calls initDatabase()
- Better console output with status indicators

### Documentation

**New Files:**
- `DATABASE.md` - Complete schema reference
- `CLEANUP_NOTES.md` - Lists outdated files to remove
- `RELEASE_NOTES_v0.4.0.md` - This file

**Updated Files:**
- `README.md` - Current features and setup instructions
- `ROADMAP.md` - Accurate progress tracking and version history

**Outdated Files (Manual Deletion Required):**
- `DATABASE_MIGRATIONS.md`
- `DEPLOY_NOW.md`
- `FEATURE_IMPLEMENTATION.md`
- `FRONTEND_FIX_REQUIRED.md`
- `IMPLEMENTATION_PLAN.md`
- `SPRINT1_PEDIGREE_COMPLETE.md`
- `migrate-now.sh`

See `CLEANUP_NOTES.md` for details.

---

## 🚀 Upgrade Instructions

### For Fresh Installs

No action needed! The database will initialize correctly:

```bash
git clone https://git.alwisp.com/jason/breedr.git
cd breedr
git checkout docs/clean-schema-and-roadmap-update
docker-compose up -d
```

### For Existing Installations

**Important:** This update requires starting with a fresh database.

1. **Backup your data:**
   ```bash
   cp data/breedr.db data/breedr.db.backup
   ```

2. **Stop the application:**
   ```bash
   docker-compose down
   ```

3. **Delete old database:**
   ```bash
   rm data/breedr.db
   ```

4. **Pull latest code:**
   ```bash
   git pull origin docs/clean-schema-and-roadmap-update
   ```

5. **Rebuild and restart:**
   ```bash
   docker-compose up -d --build
   ```

6. **Verify database:**
   ```bash
   docker exec -it breedr sqlite3 /app/data/breedr.db ".schema dogs"
   ```

   You should see `litter_id` but **NO** `sire_id`, `dam_id`, `weight`, or `height` columns.

### Data Migration Notes

**Parent Relationships:**
- Cannot be automatically migrated due to schema change
- You'll need to re-enter sire/dam relationships for existing dogs
- Use the dog edit form or litter linking feature

**All Other Data:**
- Basic dog info (name, breed, sex, etc.) can be re-entered
- Photos will need to be re-uploaded
- Consider this a fresh start with a clean, correct schema

---

## 🐛 Bug Fixes

- ✅ **Fixed:** "no such column: sire" errors
- ✅ **Fixed:** "no such column: weight" errors  
- ✅ **Fixed:** "no such column: height" errors
- ✅ **Fixed:** Parent relationships not saving properly
- ✅ **Fixed:** Schema detection failures on startup
- ✅ **Fixed:** Migration system complexity

---

## 📚 Documentation Updates

### DATABASE.md

Comprehensive database documentation including:
- Schema design principles
- All table structures with SQL
- API usage examples
- Query examples for relationships
- Fresh install instructions
- Troubleshooting guide

### README.md

Updated with:
- Current feature list
- Clean schema explanation
- Fresh install vs upgrade instructions
- Troubleshooting for common errors
- Links to documentation

### ROADMAP.md

Updated with:
- Phase 1-3 marked complete
- v0.4.0 release notes
- Current sprint focus recommendations
- Version history

---

## 🧐 Developer Notes

### New Development Workflow

**For database changes:**
1. Edit `server/db/init.js` only
2. Test with fresh database: `rm data/breedr.db && npm run dev`
3. Update `DATABASE.md` documentation
4. No migrations needed!

**For API changes involving parents:**
- Use `parents` table for sire/dam relationships
- Check `server/routes/dogs.js` for examples
- Log relationship creation for debugging

### Testing

Test these scenarios:
1. Fresh install - database created correctly
2. Add dog with sire/dam - parents table populated
3. Add dog via litter - litter_id set, parents auto-linked
4. View dog details - parents and offspring shown correctly
5. Pedigree view - multi-generation tree displays

---

## 📊 What's Next

### Recommended Next Features

1. **Trial Pairing Simulator** (4-6 hours)
   - Uses existing COI calculator backend
   - High value for breeding decisions
   - Relatively quick to implement

2. **Health Records System** (6-8 hours)
   - Important for breeding decisions  
   - Vaccination tracking
   - Document management

3. **Heat Cycle Management** (6-8 hours)
   - Natural extension of litter management
   - Calendar functionality
   - Breeding planning

See `ROADMAP.md` for full details.

---

## ℹ️ Support

**Documentation:**
- [DATABASE.md](DATABASE.md) - Schema reference
- [README.md](README.md) - Project overview
- [ROADMAP.md](ROADMAP.md) - Development plan
- [CLEANUP_NOTES.md](CLEANUP_NOTES.md) - File cleanup guide

**Common Issues:**
- "no such column" errors → Delete database and restart
- Parents not saving → Check server logs for relationship creation
- Schema looks wrong → Verify with `.schema dogs` command

**Logs:**
```bash
docker logs breedr
```

---

## 🎉 Credits

Clean schema design and implementation by the BREEDR development team.

Special thanks for thorough testing and validation of the new database architecture.

---

## 📝 Changelog Summary

### Added
- Clean database initialization system
- `dogs.litter_id` column
- `parents` table for relationships  
- DATABASE.md documentation
- Detailed logging for debugging
- CLEANUP_NOTES.md
- RELEASE_NOTES_v0.4.0.md

### Changed
- Database init is now single source of truth
- Parent relationships use parents table
- README.md updated
- ROADMAP.md updated
- Simplified server startup

### Removed
- Migration system (`server/db/migrations.js`)
- `dogs.weight` column
- `dogs.height` column
- `dogs.sire_id` column
- `dogs.dam_id` column
- Schema detection logic
- Outdated documentation (marked for deletion)

### Fixed
- "no such column" errors
- Parent relationship saving
- Schema consistency issues
- Migration failures

---

**Full Diff:** [Compare branches on Gitea](https://git.alwisp.com/jason/breedr/compare/feature/enhanced-litters-and-pedigree...docs/clean-schema-and-roadmap-update)

**Next Release:** v0.5.0 - Trial Pairing Simulator (planned)