docs/community-governance.md
This document describes maintainer expectations, project governance, and the detailed pull request review workflow (labels, merge queue, commit message format for mergers). For what contributors should do when opening and updating a PR, see CONTRIBUTING.md.
A PR should only be assigned to a milestone if it will likely be merged into the given version.
PRs without a milestone may not be merged.
Almost all labels used inside Gitea can be classified as one of the following:
modifies/…: Determines which parts of the codebase are affected. These labels will be set through the CI.topic/…: Determines the conceptual component of Gitea that is affected, i.e. issues, projects, or authentication. At best, PRs should only target one component but there might be overlap. Must be set manually.type/…: Determines the type of an issue or PR (feature, refactoring, docs, bug, …). If GitHub supported scoped labels, these labels would be exclusive, so you should set exactly one, not more or less (every PR should fall into one of the provided categories, and only one).issue/… / lgtm/…: Labels that are specific to issues or PRs respectively and that are only necessary in a given context, i.e. issue/not-a-bug or lgtm/need 2Every PR should be labeled correctly with every label that applies.
There are also some labels that will be managed automatically.
In particular, these are
backports or needs a manual backportMaintainers are encouraged to review pull requests in areas where they have expertise or particular interest.
Changes to Gitea must be reviewed before they are accepted, including changes from owners and maintainers. The exception is critical bugs that prevent Gitea from compiling or starting.
We require two maintainer approvals for every PR. When that is satisfied, your PR gets the lgtm/done label. After that, you mainly fix merge conflicts and respond to or implement maintainer requests; maintainers drive getting the PR merged.
If a PR has lgtm/done, no open discussions, and no merge conflicts, any maintainer may add reviewed/wait-merge. That puts the PR in the merge queue. PRs are merged from the queue in the order of this list:
Gitea uses its own tool, https://github.com/go-gitea/gitea/blob/main/.github/workflows/giteabot.yml, to automate parts of the review process. The backporter:
If a PR has been ignored for more than 7 days with no comments or reviews, and the author or any maintainer believes it will not survive a long wait (such as a refactoring PR), they can send "final call" to the TOC by mentioning them in a comment.
After another 7 days, if there is still zero approval, this is considered a polite refusal, and the PR will be closed to avoid wasting further time. Therefore, the "final call" has a cost, and should be used cautiously.
However, if there are no objections from maintainers, the PR can be merged with only one approval from the TOC (not the author).
Mergers are required to rewrite the PR title and the first comment (the summary) when necessary so the squash commit message is clear.
The final commit message should not hedge: replace phrases like hopefully, <x> won't happen anymore with definite wording.
A person counts as a PR co-author once they (co-)authored a commit that is not simply a Merge base branch into branch commit. Mergers must remove such false-positive co-authors when writing the squash message. Every true co-author must remain in the commit message.
mainThe commit message of PRs targeting main is always
$PR_TITLE ($PR_INDEX)
$REWRITTEN_PR_SUMMARY
The commit message of backport PRs is always
$PR_TITLE ($INITIAL_PR_INDEX) ($BACKPORT_PR_INDEX)
$REWRITTEN_PR_SUMMARY
We list maintainers so every PR gets proper review.
Every PR must be reviewed by at least two maintainers (or owners) before merge. Exception: after one week, refactoring PRs and documentation-only PRs need only one maintainer approval.
Maintainers are expected to spend time on code reviews.
A maintainer should already be a Gitea contributor with at least four merged PRs. To apply, use the Discord #develop channel. Maintainer teams may also invite contributors.
If you cannot keep reviewing, apply to leave the maintainers team. You can join the advisors team; advisors who want to review again are welcome back as maintainers.
If a maintainer is inactive for more than three months and has not left the team, owners may move them to the advisors team.
For security, maintainers should enable 2FA and sign commits with GPG when possible:
Any account with write access (including bots and TOC members) must use 2FA.
Mergers are the maintainers who carry out the final merge of approved PRs. Their responsibilities, described throughout this guide, are:
lgtm/done, no open discussions, and no merge conflicts.type/…) needed for changelog and backport decisions.A merger must already be a Gitea maintainer.
To apply, use the Discord #maintainers channel.
The minimum requirement for applications to become a merger is to have participated actively in the community for at least four months before applying.
Ultimately, regardless of previous participation, you can only become a merger if the TOC votes in your favor.
You may also be invited by the TOC to become a merger.
At the start of 2023, the Owners team was dissolved. Instead, the governance charter proposed a technical oversight committee (TOC) which expands the ownership team of the Gitea project from three elected positions to six positions. Three positions are elected as it has been over the past years, and the other three consist of appointed members from the Gitea company.
https://blog.gitea.com/quarterly-23q1/
Any maintainer is eligible to be part of the community TOC if they are not associated with the Gitea company. A maintainer can either nominate themselves, or can be nominated by other maintainers to be a candidate for the TOC election. If you are nominated by someone else, you must first accept your nomination before the vote starts to be a candidate.
The TOC is elected for one year, the TOC election happens yearly. After the announcement of the results of the TOC election, elected members have two weeks time to confirm or refuse the seat. If an elected member does not answer within this timeframe, they are automatically assumed to refuse the seat. Refusals result in the person with the next highest vote getting the same choice. As long as seats are empty in the TOC, members of the previous TOC can fill them until an elected member accepts the seat.
If an elected member that accepts the seat does not have 2FA configured yet, they will be temporarily counted as answer pending until they manage to configure 2FA, thus leaving their seat empty for this duration.
If multiple persons have the same amount of votes, a random draw will be used to determine the order of the candidates with the same amount of votes, and thus who gets the seat first. The candidates will be placed in the list in an alphabetical insensitive order by their username. We use this script to determine the order of candidates with the same amount of votes:
import random
random.seed("Gitea TOC <YEAR> Election")
random.choice([<CANDIDATE_1>, <CANDIDATE_2>, ...])
The result of this script needs then to be published in the TOC election issue to ensure transparency of the process.
Here's the history of the owners and the time they served:
Each member of the community elected TOC will be granted $500 each month as compensation for their work.
Furthermore, any community release manager for a specific release or LTS will be compensated $500 for the delivery of said release.
These funds will come from community sources like the OpenCollective rather than directly from the company. Only non-company members are eligible for this compensation, and if a member of the community TOC takes the responsibility of release manager, they would only be compensated for their TOC duties. Gitea Ltd employees are not eligible to receive any funds from the OpenCollective unless it is reimbursement for a purchase made for the Gitea project itself.
Each year a roadmap will be discussed with the entire Gitea maintainers team, and feedback will be solicited from various stakeholders. TOC members need to review the roadmap every year and work together on the direction of the project.
When a vote is required for a proposal or other change, the vote of community elected TOC members count slightly more than the vote of company elected TOC members. With this approach, we both avoid ties and ensure that changes align with the mission statement and community opinion.
You can visit our roadmap on the wiki.