4 min lectura • Guide 432 of 877
How to Track Development Environment Issues?
How to track development environment issues?
Track environment issues by creating dedicated tasks for blocking problems, documenting workarounds in task comments, using labels to identify environment-related work (env:local, env:docker), and maintaining a troubleshooting guide in NoteVault. Prioritize environment fixes that block multiple developers over single-developer issues.
Environment issue labels
| Label | Purpose |
|---|---|
| env:issue | Environment problem |
| env:local | Local development |
| env:docker | Docker-related |
| env:dependency | Dependency issue |
| env:ci | CI environment |
| blocking | Blocks development |
| workaround:available | Has temporary fix |
| recurring | Happens repeatedly |
Environment issue template
## Env Issue: [Brief Description]
### Impact
- Developers affected: 3/5
- Blocking: Yes
- Workaround: Available
### Symptoms
[What developers see when issue occurs]
### Steps to Reproduce
1. [Step 1]
2. [Step 2]
3. [Error occurs]
### Workaround
[Temporary fix if available]
### Root Cause
[If known]
### Fix
- [ ] Identify root cause
- [ ] Develop fix
- [ ] Test fix
- [ ] Update documentation
- [ ] Notify team
### Prevention
[How to prevent recurrence]
Environment issue severity
| Severity | Criteria | Response |
|---|---|---|
| Critical | Blocks whole team | Fix immediately |
| High | Blocks some developers, no workaround | Fix today |
| Medium | Blocks some, workaround exists | Fix this sprint |
| Low | Annoying, easy workaround | Fix when convenient |
NoteVault troubleshooting guide
# Development Environment Troubleshooting
## Quick Fixes
### Docker containers won't start
docker-compose down -v docker-compose up -d --build
### Node modules issues
rm -rf node_modules package-lock.json npm install
### Database connection refused
1. Check Docker is running
2. Verify port 5432 is free
3. Check DATABASE_URL in .env
## Known Issues
### M1 Mac: Docker performance
**Workaround**: Use Rosetta in Docker settings
**Status**: No permanent fix
### Windows: Line endings
**Fix**: Configure git: `git config --global core.autocrlf true`
**Prevention**: Add .gitattributes to repo
## Environment Health Check
Run this to verify setup:
npm run env:check
Expected output:
- ✓ Node version: 20.x
- ✓ Database connection: OK
- ✓ Redis connection: OK
- ✓ API health: OK
Environment issue workflow:
- Report issue - Create task with details
- Assess impact - How many developers blocked?
- Find workaround - Unblock developers quickly
- Document workaround - Share immediately
- Root cause - Investigate underlying issue
- Fix permanently - Implement proper solution
- Update docs - Add to troubleshooting guide
- Notify team - Announce fix
Preventing environment issues
| Prevention | Implementation |
|---|---|
| Containerize | Docker for all dependencies |
| Automate setup | Single command setup script |
| Document thoroughly | Step-by-step with versions |
| Version lock | Lock dependency versions |
| CI validation | Test setup in CI |
| Regular updates | Keep tools current |