123 lines
3.8 KiB
Markdown
123 lines
3.8 KiB
Markdown
# webref
|
|
|
|
A Python project for web reference management, built with quality and maintainability as core values.
|
|
|
|
## Project Constitution
|
|
|
|
This project follows a formal constitution that establishes binding principles for all development work. The constitution ensures consistent quality, testing discipline, user experience, and performance across the codebase.
|
|
|
|
**Constitutional Principles:**
|
|
1. **Code Quality & Maintainability** - Clear, consistent, maintainable code with proper typing and documentation
|
|
2. **Testing Discipline** - ≥80% coverage, automated testing for all functionality
|
|
3. **User Experience Consistency** - Intuitive, accessible, consistent interfaces
|
|
4. **Performance & Efficiency** - Performance-first design with bounded resources
|
|
|
|
📖 **Full constitution:** [`.specify/memory/constitution.md`](.specify/memory/constitution.md)
|
|
|
|
## Development Environment
|
|
|
|
This project uses Nix for reproducible development environments:
|
|
|
|
```bash
|
|
# Enter development shell
|
|
nix-shell
|
|
|
|
# Or use direnv for automatic activation
|
|
echo "use nix" > .envrc
|
|
direnv allow
|
|
```
|
|
|
|
**Included tools:**
|
|
- Python 3 with setuptools
|
|
- uv (fast Python package manager)
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
webref/
|
|
├── .specify/ # Project governance and templates
|
|
│ ├── memory/
|
|
│ │ └── constitution.md # Project constitution
|
|
│ └── templates/
|
|
│ ├── plan-template.md # Planning document template
|
|
│ ├── spec-template.md # Specification template
|
|
│ ├── tasks-template.md # Task tracking template
|
|
│ └── commands/
|
|
│ └── constitution.md # Constitution amendment workflow
|
|
├── shell.nix # Nix development environment
|
|
└── README.md # This file
|
|
```
|
|
|
|
## Using the Specification System
|
|
|
|
### Planning a Feature
|
|
|
|
1. Copy `.specify/templates/plan-template.md` to `.specify/plans/[feature-name].md`
|
|
2. Fill in objectives, scope, and technical approach
|
|
3. Complete the Constitution Alignment Check to verify adherence to principles
|
|
4. Review with team before proceeding to specification
|
|
|
|
### Writing a Specification
|
|
|
|
1. Copy `.specify/templates/spec-template.md` to `.specify/specs/[feature-name].md`
|
|
2. Define functional and non-functional requirements
|
|
3. Each requirement must address constitutional alignment (testing, UX, performance)
|
|
4. Include clear acceptance criteria for validation
|
|
|
|
### Managing Tasks
|
|
|
|
1. Copy `.specify/templates/tasks-template.md` to `.specify/tasks/[sprint-name].md`
|
|
2. Organize tasks by constitutional principle category:
|
|
- 🏗️ Implementation (Code Quality)
|
|
- 🧪 Testing (Testing Discipline)
|
|
- 👤 User Experience (UX Consistency)
|
|
- ⚡ Performance (Performance & Efficiency)
|
|
3. Complete the checklist before closing any task
|
|
|
|
### Amending the Constitution
|
|
|
|
1. Create a pull request to `.specify/memory/constitution.md`
|
|
2. Include rationale and impact analysis
|
|
3. Update version number (MAJOR.MINOR.PATCH)
|
|
4. Update all dependent templates
|
|
5. Prepend Sync Impact Report
|
|
|
|
## Code Quality Standards
|
|
|
|
All code must meet these requirements before merge:
|
|
|
|
- ✅ Linter passing (no errors/warnings)
|
|
- ✅ Type hints on all public APIs
|
|
- ✅ Tests passing with ≥80% coverage
|
|
- ✅ Code review approved
|
|
- ✅ Constitution principles verified
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run tests
|
|
pytest
|
|
|
|
# With coverage report
|
|
pytest --cov=webref --cov-report=html
|
|
|
|
# Coverage must be ≥80% per Constitutional Principle 2
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Read the [constitution](.specify/memory/constitution.md)
|
|
2. Follow the planning → specification → implementation flow
|
|
3. Ensure all code meets constitutional principles
|
|
4. Write tests first (TDD encouraged)
|
|
5. Request code review
|
|
|
|
## License
|
|
|
|
[License information to be added]
|
|
|
|
## Contact
|
|
|
|
[Contact information to be added]
|
|
|