forked from jsnbuchanan/crowd-funder-for-time-pwa
d5786e5131
- Update main README with guard system overview - Create detailed guard implementation guide - Add PR template documentation and usage examples - Document opt-in hook activation process
119 lines
3.1 KiB
Markdown
119 lines
3.1 KiB
Markdown
# Time Safari Application
|
|
|
|
**Author**: Matthew Raymer
|
|
**Version**: 1.0.8-beta
|
|
**Description**: Time Safari Application
|
|
|
|
## 🛡️ Build Architecture Guard
|
|
|
|
This project uses **Husky Git hooks** to protect the build system
|
|
architecture. When you modify build-critical files, the system
|
|
automatically blocks commits until you update `BUILDING.md`.
|
|
|
|
### Quick Setup
|
|
|
|
```bash
|
|
npm run guard:setup # Install and activate the guard
|
|
```
|
|
|
|
### How It Works
|
|
|
|
- **Pre-commit**: Blocks commits if build files changed without
|
|
BUILDING.md updates
|
|
- **Pre-push**: Blocks pushes if commits contain undocumented build
|
|
changes
|
|
- **Protected paths**: `scripts/`, `vite.config.*`, `electron/`,
|
|
`android/`, `ios/`, etc.
|
|
|
|
### Usage
|
|
|
|
```bash
|
|
# Test the guard manually
|
|
npm run guard:test
|
|
|
|
# Emergency bypass (use sparingly)
|
|
git commit --no-verify
|
|
git push --no-verify
|
|
```
|
|
|
|
**📚 Full documentation**: See `README-BUILD-GUARD.md`
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 18+
|
|
- npm, yarn, or pnpm
|
|
- Git
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
npm install
|
|
npm run guard:setup # Sets up Build Architecture Guard
|
|
```
|
|
|
|
### Development
|
|
|
|
```bash
|
|
npm run build:web:dev # Build web version
|
|
npm run build:ios:test # Build iOS test version
|
|
npm run build:android:test # Build Android test version
|
|
npm run build:electron:dev # Build Electron dev version
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
npm run test:web # Run web tests
|
|
npm run test:mobile # Run mobile tests
|
|
npm run test:all # Run all tests
|
|
```
|
|
|
|
## 📁 Project Structure
|
|
|
|
```text
|
|
timesafari/
|
|
├── 📁 src/ # Source code
|
|
├── 📁 scripts/ # Build and automation scripts
|
|
├── 📁 electron/ # Electron configuration
|
|
├── 📁 android/ # Android configuration
|
|
├── 📁 ios/ # iOS configuration
|
|
├── 📁 .husky/ # Git hooks (Build Architecture Guard)
|
|
├── 📄 BUILDING.md # Build system documentation
|
|
├── 📄 pull_request_template.md # PR template
|
|
└── 📄 README-BUILD-GUARD.md # Guard system documentation
|
|
```
|
|
|
|
## 🔧 Build System
|
|
|
|
This project supports multiple platforms:
|
|
|
|
- **Web**: Vite-based build with service worker support
|
|
- **Mobile**: Capacitor-based iOS and Android builds
|
|
- **Desktop**: Electron-based cross-platform desktop app
|
|
- **Docker**: Containerized deployment options
|
|
|
|
## 📚 Documentation
|
|
|
|
- **`BUILDING.md`** - Complete build system guide
|
|
- **`README-BUILD-GUARD.md`** - Build Architecture Guard documentation
|
|
- **`pull_request_template.md`** - PR template for build changes
|
|
|
|
## 🤝 Contributing
|
|
|
|
1. **Follow the Build Architecture Guard** - Update BUILDING.md when modifying build files
|
|
2. **Use the PR template** - Complete the checklist for build-related changes
|
|
3. **Test your changes** - Ensure builds work on affected platforms
|
|
4. **Document updates** - Keep BUILDING.md current and accurate
|
|
|
|
## 📄 License
|
|
|
|
[Add your license information here]
|
|
|
|
---
|
|
|
|
**Note**: The Build Architecture Guard is active and will block
|
|
commits/pushes that modify build files without proper documentation
|
|
updates. See `README-BUILD-GUARD.md` for complete details.
|