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/yourusername/gitea-mirror.git
cd gitea-mirror

2. Install dependencies:

bun install

3. Initialize database:

bun run init-db

4. Configure environment:

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

5. Start development server:

bun run dev

Development Commands

Command	Description
bun run dev	Start development server with hot reload
bun run build	Build for production
bun run preview	Preview production build
bun test	Run all tests
bun test:watch	Run tests in watch mode
bun run db:studio	Open database GUI

Project Structure

gitea-mirror/
├── src/
│   ├── components/      # React components
│   ├── pages/          # Astro pages & API routes
│   ├── lib/            # Core logic
│   │   ├── db/         # Database queries
│   │   ├── utils/      # Helper functions
│   │   └── modules/    # Module system
│   ├── hooks/          # React hooks
│   └── types/          # TypeScript types
├── public/             # Static assets
├── scripts/            # Utility scripts
└── tests/              # Test files

Feature Development

Adding a New Feature

1. Create feature branch:

git checkout -b feature/my-feature

2. Plan your changes:

• UI components in /src/components/
• API endpoints in /src/pages/api/
• Database queries in /src/lib/db/queries/
• Types 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 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