gitea-mirror/docs/DEVELOPMENT_WORKFLOW.md

Development Workflow

This guide covers the development workflow for the open-source Gitea Mirror.

Getting Started

Prerequisites

• Bun >= 1.2.9
• Node.js >= 20
• Git
• GitHub account (for API access)
• Gitea instance (for testing)

Initial Setup

1. Clone the repository:

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

2. Install dependencies and seed the SQLite database:

bun run setup

3. Configure environment (optional):

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

4. Start the development server:

bun run dev

Development Commands

Command	Description
bun run dev	Start the Bun + Astro dev server with hot reload
bun run build	Build the production bundle
bun run preview	Preview the production build locally
bun test	Run the Bun test suite
bun test:watch	Run tests in watch mode
bun run db:studio	Launch Drizzle Kit Studio

Project Structure

gitea-mirror/
├── src/                     # Application UI, API routes, and services
│   ├── components/          # React components rendered inside Astro pages
│   ├── pages/               # Astro pages and API routes (e.g., /api/*)
│   ├── lib/                 # Core logic: GitHub/Gitea clients, scheduler, recovery, db helpers
│   │   ├── db/              # Drizzle adapter + schema
│   │   ├── modules/         # Module wiring (jobs, integrations)
│   │   └── utils/           # Shared utilities
│   ├── hooks/               # React hooks
│   ├── content/             # In-app documentation and templated content
│   ├── layouts/             # Shared layout components
│   ├── styles/              # Tailwind CSS entrypoints
│   └── types/               # TypeScript types
├── scripts/                 # Bun scripts for DB management and maintenance
├── www/                     # Marketing site (Astro + MDX use cases)
├── public/                  # Static assets served by Vite/Astro
└── tests/                   # Dedicated integration/unit test helpers

Feature Development

Adding a New Feature

1. Create feature branch:

git checkout -b feature/my-feature

2. Plan your changes:

• UI components live in src/components/
• API endpoints live in src/pages/api/
• Database logic is under src/lib/db/ (schema + adapter)
• Shared types are in src/types/

3. Implement the feature:

Example: Adding a new API endpoint

// src/pages/api/my-endpoint.ts
import type { APIRoute } from 'astro';
import { getUserFromCookie } from '@/lib/auth-utils';

export const GET: APIRoute = async ({ request }) => {
  const user = await getUserFromCookie(request);
  if (!user) {
    return new Response('Unauthorized', { status: 401 });
  }

  // Your logic here
  return new Response(JSON.stringify({ data: 'success' }), {
    headers: { 'Content-Type': 'application/json' }
  });
};

4. Write tests:

// src/lib/my-feature.test.ts
import { describe, it, expect } from 'bun:test';

describe('My Feature', () => {
  it('should work correctly', () => {
    expect(myFunction()).toBe('expected');
  });
});

5. Update documentation:

• Add JSDoc comments
• Update README/docs if needed
• Document API changes

Database Development

Schema Changes

1. Modify schema:

// src/lib/db/schema.ts
export const myTable = sqliteTable('my_table', {
  id: text('id').primaryKey(),
  name: text('name').notNull(),
  createdAt: integer('created_at').notNull(),
});

2. Generate migration:

bun run db:generate

3. Apply migration:

bun run db:migrate

Writing Queries

// src/lib/db/queries/my-queries.ts
import { db } from '../index';
import { myTable } from '../schema';

export async function getMyData(userId: string) {
  return db.select()
    .from(myTable)
    .where(eq(myTable.userId, userId));
}

Testing

Unit Tests

# Run all tests
bun test

# Run specific test file
bun test auth

# Watch mode
bun test:watch

# Coverage
bun test:coverage

Manual Testing Checklist

• Feature works as expected
• No console errors
• Responsive on mobile
• Handles errors gracefully
• Loading states work
• Form validation works
• API returns correct status codes

Debugging

VSCode Configuration

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "bun",
      "request": "launch", 
      "name": "Debug Bun",
      "program": "${workspaceFolder}/src/index.ts",
      "cwd": "${workspaceFolder}",
      "env": {
        "NODE_ENV": "development"
      }
    }
  ]
}

Debug Logging

// Development only logging
if (import.meta.env.DEV) {
  console.log('[Debug]', data);
}

Code Style

TypeScript

• Use strict mode
• Define interfaces for all data structures
• Avoid any type
• Use proper error handling

React Components

• Use functional components
• Implement proper loading states
• Handle errors with error boundaries
• Use TypeScript for props

API Routes

• Always validate input
• Return proper status codes
• Use consistent error format
• Document with JSDoc

Git Workflow

Commit Messages

Follow conventional commits:

feat: add repository filtering
fix: resolve sync timeout issue
docs: update API documentation
style: format code with prettier
refactor: simplify auth logic
test: add user creation tests
chore: update dependencies

Pull Request Process

1. Create feature branch
2. Make changes
3. Write/update tests
4. Update documentation
5. Create PR with description
6. Address review feedback
7. Squash and merge

Performance

Development Tips

• Use React DevTools
• Monitor bundle size
• Profile database queries
• Check memory usage

Optimization

• Lazy load components
• Optimize images
• Use database indexes
• Cache API responses

Common Issues

Port Already in Use

# Use different port
PORT=3001 bun run dev

Database Locked

# Reset database
bun run cleanup-db
bun run init-db

Type Errors

# Check types
bunx tsc --noEmit

Release Process

1. Update version:

npm version patch  # or minor/major

2. Update CHANGELOG.md

3. Build and test:

bun run build
bun test

4. Create release:

git tag v2.23.0
git push origin v2.23.0

5. Create GitHub release

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to your fork
5. Create a Pull Request

Resources

• Astro Documentation
• Bun Documentation
• Drizzle ORM
• React Documentation
• TypeScript Handbook

Getting Help

• Check existing issues
• Join discussions
• Read the FAQ