Updated docs

Author: arunavo4

CONTRIBUTING.md

@@ -0,0 +1,182 @@
+# Contributing to Gitea Mirror
+
+Thank you for your interest in contributing to Gitea Mirror! This document provides guidelines and instructions for contributing to the open-source version of the project.
+
+## 🎯 Project Overview
+
+Gitea Mirror is an open-source, self-hosted solution for mirroring GitHub repositories to Gitea instances. This guide provides everything you need to know about contributing to the project.
+
+## 🚀 Getting Started
+
+1. Fork the repository
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/yourusername/gitea-mirror.git
+   cd gitea-mirror
+   ```
+
+3. Install dependencies:
+   ```bash
+   bun install
+   ```
+
+4. Set up your environment:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your configuration
+   ```
+
+5. Start development:
+   ```bash
+   bun run dev
+   ```
+
+## 🛠 Development Workflow
+
+### Running the Application
+
+```bash
+# Development mode
+bun run dev
+
+# Build for production
+bun run build
+
+# Run tests
+bun test
+```
+
+### Database Management
+
+```bash
+# Initialize database
+bun run init-db
+
+# Reset database
+bun run cleanup-db && bun run init-db
+```
+
+## 📝 Code Guidelines
+
+### General Principles
+
+1. **Keep it Simple**: Gitea Mirror should remain easy to self-host
+2. **Focus on Core Features**: Prioritize repository mirroring and synchronization
+3. **Database**: Use SQLite for simplicity and portability
+4. **Dependencies**: Minimize external dependencies for easier deployment
+
+### Code Style
+
+- Use TypeScript for all new code
+- Follow the existing code formatting (Prettier is configured)
+- Write meaningful commit messages
+- Add tests for new features
+
+### Scope of Contributions
+
+This project focuses on personal/small team use cases. Please keep contributions aligned with:
+- Core mirroring functionality
+- Self-hosted simplicity
+- Minimal external dependencies
+- SQLite as the database
+- Single-instance deployments
+
+## 🐛 Reporting Issues
+
+1. Check existing issues first
+2. Use issue templates when available
+3. Provide clear reproduction steps
+4. Include relevant logs and screenshots
+
+## 🎯 Pull Request Process
+
+1. Create a feature branch:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes following the code guidelines
+
+3. Test your changes:
+   ```bash
+   # Run tests
+   bun test
+   
+   # Build and check
+   bun run build:oss
+   ```
+
+4. Commit your changes:
+   ```bash
+   git commit -m "feat: add new feature"
+   ```
+
+5. Push to your fork and create a Pull Request
+
+### PR Requirements
+
+- Clear description of changes
+- Tests for new functionality
+- Documentation updates if needed
+- No breaking changes without discussion
+- Passes all CI checks
+
+## 🏗 Architecture Overview
+
+```
+src/
+├── components/     # React components
+├── lib/           # Core utilities
+│   ├── db/        # Database queries (SQLite only)
+│   ├── github/    # GitHub API integration
+│   ├── gitea/     # Gitea API integration
+│   └── utils/     # Helper functions
+├── pages/         # Astro pages
+│   └── api/       # API endpoints
+└── types/         # TypeScript types
+```
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+bun test
+
+# Run tests in watch mode
+bun test:watch
+
+# Run with coverage
+bun test:coverage
+```
+
+## 📚 Documentation
+
+- Update README.md for user-facing changes
+- Add JSDoc comments for new functions
+- Update .env.example for new environment variables
+
+## 💡 Feature Requests
+
+We welcome feature requests! When proposing new features, please consider:
+- Does it enhance the core mirroring functionality?
+- Will it benefit self-hosted users?
+- Can it be implemented without complex external dependencies?
+- Does it maintain the project's simplicity?
+
+## 🤝 Community
+
+- Be respectful and constructive
+- Help others in issues and discussions
+- Share your use cases and feedback
+
+## 📄 License
+
+By contributing, you agree that your contributions will be licensed under the same license as the project (MIT).
+
+## Questions?
+
+Feel free to open an issue for any questions about contributing!
+
+---
+
+Thank you for helping make Gitea Mirror better! 🎉

docs/BUILD_GUIDE.md

@@ -0,0 +1,205 @@
+# Build Guide
+
+This guide covers building the open-source version of Gitea Mirror.
+
+## Prerequisites
+
+- **Bun** >= 1.2.9 (primary runtime)
+- **Node.js** >= 20 (for compatibility)
+- **Git**
+
+## Quick Start
+
+```bash
+# Clone repository
+git clone https://github.com/yourusername/gitea-mirror.git
+cd gitea-mirror
+
+# Install dependencies
+bun install
+
+# Initialize database
+bun run init-db
+
+# Build for production
+bun run build
+
+# Start the application
+bun run start
+```
+
+## Build Commands
+
+| Command | Description |
+|---------|-------------|
+| `bun run build` | Production build |
+| `bun run dev` | Development server |
+| `bun run preview` | Preview production build |
+| `bun test` | Run tests |
+| `bun run cleanup-db` | Remove database files |
+
+## Build Output
+
+The build creates:
+- `dist/` - Production-ready server files
+- `.astro/` - Build cache (git-ignored)
+- `data/` - SQLite database location
+
+## Development Build
+
+For active development with hot reload:
+
+```bash
+bun run dev
+```
+
+Access the application at http://localhost:4321
+
+## Production Build
+
+```bash
+# Build
+bun run build
+
+# Test the build
+bun run preview
+
+# Run in production
+bun run start
+```
+
+## Docker Build
+
+```dockerfile
+# Build Docker image
+docker build -t gitea-mirror:latest .
+
+# Run container
+docker run -p 3000:3000 gitea-mirror:latest
+```
+
+## Environment Variables
+
+Create a `.env` file:
+
+```env
+# Database
+DATABASE_PATH=./data/gitea-mirror.db
+
+# Authentication
+JWT_SECRET=your-secret-here
+
+# GitHub Configuration
+GITHUB_TOKEN=ghp_...
+GITHUB_WEBHOOK_SECRET=...
+
+# Gitea Configuration
+GITEA_URL=https://your-gitea.com
+GITEA_TOKEN=...
+```
+
+## Common Build Issues
+
+### Missing Dependencies
+
+```bash
+# Solution
+bun install
+```
+
+### Database Not Initialized
+
+```bash
+# Solution
+bun run init-db
+```
+
+### Port Already in Use
+
+```bash
+# Change port
+PORT=3001 bun run dev
+```
+
+### Build Cache Issues
+
+```bash
+# Clear cache
+rm -rf .astro/ dist/
+bun run build
+```
+
+## Build Optimization
+
+### Development Speed
+
+- Use `bun run dev` for hot reload
+- Skip type checking during rapid development
+- Keep `.astro/` cache between builds
+
+### Production Optimization
+
+- Minification enabled automatically
+- Tree shaking removes unused code
+- Image optimization with Sharp
+
+## Validation
+
+After building, verify:
+
+```bash
+# Check build output
+ls -la dist/
+
+# Test server starts
+bun run start
+
+# Check health endpoint
+curl http://localhost:3000/api/health
+```
+
+## CI/CD Build
+
+Example GitHub Actions workflow:
+
+```yaml
+name: Build and Test
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install
+      - run: bun run build
+      - run: bun test
+```
+
+## Troubleshooting
+
+### Build Fails
+
+1. Check Bun version: `bun --version`
+2. Clear dependencies: `rm -rf node_modules && bun install`
+3. Check for syntax errors: `bunx tsc --noEmit`
+
+### Runtime Errors
+
+1. Check environment variables
+2. Verify database exists
+3. Check file permissions
+
+## Performance
+
+Expected build times:
+- Clean build: ~5-10 seconds
+- Incremental build: ~2-5 seconds
+- Development startup: ~1-2 seconds
+
+## Next Steps
+
+- Configure with [Configuration Guide](./CONFIGURATION.md)
+- Deploy with [Deployment Guide](./DEPLOYMENT.md)
+- Set up authentication with [SSO Guide](./SSO-OIDC-SETUP.md)