Contributing to Gitea

Learn how to contribute to Gitea development - from reporting issues to submitting pull requests

Introduction

Gitea welcomes contributions from the community! Whether you’re fixing bugs, adding features, improving documentation, or translating the interface, your help is appreciated.

Before starting work on a significant change, please discuss it in an issue first to ensure alignment with the project’s goals.

Ways to Contribute

Report Bugs

Help identify and document bugs in the issue tracker

Fix Issues

Contribute code fixes for existing issues

Add Features

Propose and implement new features

Improve Docs

Enhance documentation and examples

Translate

Help translate Gitea into other languages

Review Code

Participate in code review for pull requests

Getting Started

1. Fork the Repository

   Fork go-gitea/gitea on GitHub

2. Clone Your Fork

   git clone https://github.com/YOUR_USERNAME/gitea.git
   cd gitea
   
3. Add Upstream Remote

   git remote add upstream https://github.com/go-gitea/gitea.git
   
4. Create Feature Branch

   git checkout -b feature/my-new-feature
   

Development Workflow

Making Changes

1. Keep Your Fork Updated

   git fetch upstream
   git checkout main
   git merge upstream/main
   
2. Make Your Changes

   Edit the code, add tests, and update documentation

3. Format and Lint

   Go Code

   # Format Go code
   make fmt
   
   # Lint Go code
   make lint-go
   

   Frontend Code

   # Lint JavaScript/TypeScript
   make lint-js
   
4. Run Tests

   # Run all tests
   make test
   
   # Run specific test package
   go test ./modules/git/...
   

Commit Guidelines

Follow these conventions for commit messages:

# Format: <type>: <description>
#
# Types:
# - feat: New feature
# - fix: Bug fix
# - docs: Documentation changes
# - style: Code style changes (formatting)
# - refactor: Code refactoring
# - test: Adding or updating tests
# - chore: Maintenance tasks

# Example commit messages:
feat: Add support for Git LFS v3 protocol
fix: Resolve issue with webhook delivery retries
docs: Update installation guide for Docker
refactor: Simplify user authentication logic

Add the current year to the copyright header when creating new .go files.

Submitting Pull Requests

1. Push Your Branch

   git push origin feature/my-new-feature
   
2. Create Pull Request

   Go to GitHub and create a pull request from your fork to go-gitea/gitea:main

3. Fill Out PR Template

   Provide:

   • Clear description of changes
   • Related issue numbers (use Fixes #123 for automatic closing)
   • Screenshots/videos for UI changes
   • Testing performed
4. Address Review Feedback

   Work with maintainers to refine your PR

Code Review Process

PR Requirements

• Tests: Add tests for new functionality
• Documentation: Update docs for user-facing changes
• Commits: Clean commit history (squash if needed)
• Conflicts: Resolve merge conflicts
• DCO: All commits must be signed off (Developer Certificate of Origin)

Getting PR Merged

PR Approval Process

1. Review: PRs require review from maintainers
2. Testing: Automated tests must pass
3. Approval: At least one maintainer approval required
4. Merge: Maintainers will merge approved PRs

Stale PRs

PRs with no activity for 60 days may be closed. You can always reopen if you resume work.

Developer Certificate of Origin (DCO)

All commits must include a Signed-off-by line:

# Add to individual commit
git commit -s -m "feat: Add new feature"

# Or configure Git to always sign off
git config --global format.signoff true

This certifies that you have the right to submit the code under the project’s license (MIT).

Coding Standards

Go Code

• Follow Effective Go
• Use gofmt for formatting (enforced by make fmt)
• Add comments for exported functions and types
• Write tests for new code
• Handle errors explicitly

Frontend Code

• Follow the ESLint configuration
• Use TypeScript for type safety
• Write accessible HTML
• Test in multiple browsers

Database Migrations

• Create migrations for schema changes
• Test both upgrade and downgrade paths
• Support all database backends (PostgreSQL, MySQL, SQLite, MSSQL)

Translation

Help translate Gitea through Crowdin:

1. Join Crowdin

   Create an account on Crowdin and join the Gitea project

2. Select Language

   Choose the language you want to translate

3. Translate Strings

   Translate untranslated strings or improve existing translations

4. Review

   Participate in translation review and discussion

Security Issues

Do not report security issues publicly. Send them privately to [e-mail]

Community

Connect with other contributors:

• Discord: Join the Gitea Discord
• Forum: Discourse Forum
• GitHub Discussions: go-gitea/gitea discussions

Resources

Building from Source

Set up your development environment

Testing Guide

Learn how to write and run tests

Architecture

Understand Gitea’s architecture

CONTRIBUTING.md

Full contribution guidelines on GitHub

For detailed contribution guidelines, see CONTRIBUTING.md in the repository.