Welcome to Forgejo

This document …

is for all contributors of Forgejo
explains the workflow from user problems to accepting fixes in Forgejo
defines responsibilities during this workflow
applies to the primary issue tracker of Forgejo

Getting started with problem reporting

It should be easy for users to drop us a problem. In particular,

users report their problem
they do not have to think about a solution (contrary to feature requests, that kinda ask you to specify how your problem should be solved)
the process is open, allowing everyone to move from problem to implementation

The stages

Issue tracking is separated into 4 stages.

Issues can be “converted” between stages:

by updating the label: Use to fast-track simple and obvious cases. Keep in mind that reading long discussions can be exhausted.
creating a new issue in the next stage: Use to summarize previous discussions and focus on the next steps, without asking people to read through all of the past discussion history. If all relevant information was moved on, the lower stage issue can be closed.

Stage 1: Triaging

Who can create: Everyone.
Responsible for these issues: All Forgejo contributors.
Goal: Collect user problems with as much data as possible, but without asking the users to think about biased solutions.
Guidelines for moving ahead:
- isolated technical issues: try to assist as good as possible, close issue when resolved
- not clear enough: try to ask for more information
- not clear enough and the user research team might want to take a look: convert to stage-2 (research)
- probably out of scope (e.g. for needs that likely don’t align to our user base): close the issue
- the user report is outdated (e.g. because Forgejo advanced in this area): close the issue, optionally ask for re-evaluation
- problem is well defined, but finding a solution is not trivial: convert to stage-3 (design)
- problem is well defined and a solution can be implemented (“bugs”): convert to stage-4/implementation

Stage 2: Research

Who can create: Forgejo maintainers and contributors.
Responsible for these issues: All Forgejo contributors, but in particular the user research team.
Goal: Research about user needs or other requirements is conducted. Examples where this can be useful:
- How do users expect this to work? How do they configure the software? How do they use it?
- Which requirements do we need to address? Are there legal ones or standards to consider?
- How is this solved in other software? Do users expect it to work similarly? What can we learn from there?
Guidelines for moving ahead:
- data suggests this is not as important as other needs: close research and triage issues
- more data is needed: escalate to user research team
- probably enough data gathered, but solution is not obvious: convert to stage-3 (design)
- probably enough data gathered, solution seems obvious: convert to stage-4 (implementation)

Stage 3: Design

Who can create: Forgejo maintainers and contributors.
Responsible for these issues: All Forgejo contributors, but in particular the teams related to the implementation (e.g. user research and user interface team for UI/UX questions, security team for security features etc).
Goal: Discuss and specify how a problem should be solved. Can involve UI/UX discussions, but also code architecture or other technical considerations, depending on the type of change.
Guidelines for moving ahead:
- more data is needed to continue the design: create or reopen a stage-2 (research) issue
- favoured solution is found: convert to stage-4 (implementation) and document the results

Stage 4: Implementation

Who can create: Forgejo maintainers and members of at least one Forgejo team
Responsible for these issues: Forgejo developers.
Goal: Document changes that need to be implemented. They should be well-defined and not questionable.
Guidelines for moving ahead:
- implementation was merged: close this and related issues
- implementation instructions not clear enough: convert back to stage-3 (design)
- new data suggests this has become low priority: close this and related issues

Why this workflow?

good design makes a software easier and more fun to use, but the capacity of the user research team is limited
the issue tracker is a valuable source of information about user problems
this information needs to be structured and analyzed
often, a code change is reviewed for technical detail and only in the end, someone considers if the changed behaviour is actually desired
the consideration whether a change is useful happens anyway, but putting it at the start of a structured process can save development effort
we are going to learn from and iterate over the workflow, your feedback is very welcome

Resources

Living discussion about this workflow: https://codeberg.org/forgejo/discussions/issues/415
FOSDEM talk presenting the idea: https://fosdem.org/2026/schedule/event/EXQFAR-forgejo-developer-centric-user-needs-and-design/

Snippets for issue handling

Problems with related changes:

Thank you for describing your problem. We have used your feedback to influence some designs in Forgejo. Although your problem might not yet be addressed entirely, we believe that the situation has changed enough to consider this feedback as acted upon and likely outdated. However, feel free to create a new report based on your experiences with the next release of Forgejo.

Outdated problems:

Thank you for describing your problem. Unfortunately, we did not find the capacity to consider all of your input. However, Forgejo has changed significantly since the creation of your report, and I believe the situation looks different now. We’ll close this issue, but invite you to report back with your current experiences of using Forgejo.

Out of scope:

Thank you for describing your problem. Unfortunately, your needs seem to exceed the capacity of what we can currently offer as a product. I am closing your report to focus on other issues first. However, closed problem reports can still be used to gather and support changes in the future, as time and capacity permit.