gitea-mirror/CONTRIBUTING.md

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:

   git clone https://github.com/yourusername/gitea-mirror.git
   cd gitea-mirror
   

3. Install dependencies:

   bun install
   

4. Set up your environment:

   cp .env.example .env
   # Edit .env with your configuration
   

5. Start development:

   bun run dev
   

🛠 Development Workflow

Running the Application

# Development mode
bun run dev

# Build for production
bun run build

# Run tests
bun test

Database Management

# 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:

   git checkout -b feature/your-feature-name
   

2. Make your changes following the code guidelines

3. Test your changes:

   # Run tests
   bun test
   
   # Build and check
   bun run build:oss
   

4. Commit your changes:

   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

# 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! 🎉