forgejo/docs
31
58
Fork
You've already forked docs
249

Document issue tracker workflow #1983

Open
fnetX wants to merge 2 commits from fnetx/issue_workflow into next AGit
pull from: fnetx/issue_workflow
merge into: forgejo:next
forgejo:next
forgejo:v15.0
forgejo:v16.0
forgejo:v11.0
forgejo:bp-v15.0-c7697f2
forgejo:actions-remove-non-existing-strategy-options
forgejo:v14.0
forgejo:v13.0
forgejo:v12.0
forgejo:v7.0
forgejo:v10.0
forgejo:v9.0
forgejo:v8.0
forgejo:v1.21
forgejo:v1.20
forgejo:v1.19
Owner
Copy link

Related to forgejo/discussions#415
Complements forgejo/forgejo#12001

Related to https://codeberg.org/forgejo/discussions/issues/415 Complements https://codeberg.org/forgejo/forgejo/pulls/12001
Document issue tracker workflow
Some checks failed
pr / preview (pull_request_target) Failing after 23s
f8708f0aea 
Related to forgejo/discussions#415
Complements forgejo/forgejo#12001
oliverpool left a comment
Copy link

Looks sensible to me!

How would the labels be? I was thinking about classifying by "need" (to know what is the next step):

  • needs/triage (stage 1)
  • needs/more-information (stage 1)
  • needs/user-research (stage 2)
  • needs/scope-expansion (out-of-scope: closed)
  • needs/re-evaluation (outdated: closed)
  • needs/design (stage 3)
  • needs/pull-request (stage 4)
Looks sensible to me! How would the labels be? I was thinking about classifying by "need" (to know what is the next step): - `needs/triage` (stage 1) - `needs/more-information` (stage 1) - `needs/user-research` (stage 2) - `needs/scope-expansion` (out-of-scope: closed) - `needs/re-evaluation` (outdated: closed) - `needs/design` (stage 3) - `needs/pull-request` (stage 4)
@ -0,0 +31,4 @@
- **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 time might want to take a look: Create a stage-2 (research) issue

typo: time/team

typo: time/team
fnetX marked this conversation as resolved
@ -0,0 +58,4 @@
- **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: craete a stage-4 (implementation) issue and document the discussion results, close the design issue

typo: craete

typo: craete
fnetX marked this conversation as resolved
wetneb left a comment
Copy link

Nice!
I think it would be worth mentioning the situations where stages do not need to be iterated through explicitly. If I remember well, there was a consensus that straightforward bug reports don't need to go through a design phase and can be fixed directly. Similarly, there might be issues where design work is needed, but the outcome of this work is a plan that can be implemented in a straightforward way, so there wouldn't be a need for an "implementation issue": a PR can be opened directly. Overall, I imagine the workflow described here will be followed in full only for a fraction of the problems reported, no?

Also, for this workflow to be actually followed, I think we need a bigger user research team. That's perhaps not for this PR, but we should incentivize more people to join that team and get involved in the work (with some documentation about the logistical process: how do we reach out to users? Can we get some usage stats from Codeberg? where do we find a list of prominent Forgejo instances.) Maybe it would also be worth having some sort of invitation to get involved in that work in this issue_workflow.md page.

Nice! I think it would be worth mentioning the situations where stages do not need to be iterated through explicitly. If I remember well, there was a consensus that straightforward bug reports don't need to go through a design phase and can be fixed directly. Similarly, there might be issues where design work is needed, but the outcome of this work is a plan that can be implemented in a straightforward way, so there wouldn't be a need for an "implementation issue": a PR can be opened directly. Overall, I imagine the workflow described here will be followed in full only for a fraction of the problems reported, no? Also, for this workflow to be actually followed, I think we need a bigger user research team. That's perhaps not for this PR, but we should incentivize more people to join that team and get involved in the work (with some documentation about the logistical process: how do we reach out to users? Can we get some usage stats from Codeberg? where do we find a list of prominent Forgejo instances.) Maybe it would also be worth having some sort of invitation to get involved in that work in this `issue_workflow.md` page.
Author
Owner
Copy link

@oliverpool the labels are described in forgejo/forgejo#12001.

@oliverpool the labels are described in https://codeberg.org/forgejo/forgejo/pulls/12001.
Author
Owner
Copy link

I think it would be worth mentioning the situations where stages do not need to be iterated through explicitly

Do you have a suggestion on how you'd like to do it?

The "Guidelines for moving ahead" already mention how an issue can be moved from first to last stage, for instance.

Also, for this workflow to be actually followed, I think we need a bigger user research team

The goal is that the workflow is followed by everyone and that there is no "need" for a user research team to deal with the issues. The user research team could then focus on providing input only where necessary, e.g. for specific research issues.

> I think it would be worth mentioning the situations where stages do not need to be iterated through explicitly Do you have a suggestion on how you'd like to do it? The "Guidelines for moving ahead" already mention how an issue can be moved from first to last stage, for instance. > Also, for this workflow to be actually followed, I think we need a bigger user research team The goal is that the workflow is followed by everyone and that there is no "need" for a user research team to deal with the issues. The user research team could then focus on providing input only where necessary, e.g. for specific research issues.
rework issue workflow
Some checks failed
pr / preview (pull_request_target) Failing after 17s
a931fb7b42 
* address review comments
* fix linter complaints
* shorten some phrases and clarify when issues should be closed
* some other minor wording adjustments
fix lint
Some checks failed
pr / preview (pull_request_target) Failing after 20s
61ce8c3267
fix typo
All checks were successful
pr / preview (pull_request_target) Successful in 4m14s
7d17336009
Collaborator
Copy link

Preview ready: https://forgejo.codeberg.page/@docs_pull_1983/docs/next/
https://forgejo.codeberg.page/@docs_pull_1983/docs/next/contributor/issue_workflow/

Preview ready: https://forgejo.codeberg.page/@docs_pull_1983/docs/next/ https://forgejo.codeberg.page/@docs_pull_1983/docs/next/contributor/issue_workflow/
@ -0,0 +1,106 @@
---
title: 'Welcome to Forgejo'
Author
Owner
Copy link

I just realized I didn't update this. But I'm also not sure how to call the document.

"Issue workflow" seems kinda not descriptive enough, but has the advantage of being short and generic enough to apply to everyone.

"Research and design workflow" is more descriptive, but sounds like only specific people should read it (but it's for everyone!)

"Issue workflow: research and design" could combine both, but it's getting long ...

I just realized I didn't update this. But I'm also not sure how to call the document. "Issue workflow" seems kinda not descriptive enough, but has the advantage of being short and generic enough to apply to everyone. "Research and design workflow" is more descriptive, but sounds like only specific people should read it (but it's for everyone!) "Issue workflow: research and design" could combine both, but it's getting long ...
fnetX marked this conversation as resolved

It really reads well and I see forward in using it. Thanks a lot for your effort! I already see improvements of the reports since we introduced the problem/enhancement workflow. Together with the new issue templates it should have enough nudging now for users to report stage/1-triage issues (instead of enhancements). I have just some questions that aren't clear to me, yet:

  1. For the stage changes on normal track, all issues of a need are kept open until a PR closes all of them?
  2. What about issues that are triaged and not considered for continuation (you gave nice sample texts), maybe it is still worth to have labels for them for easier filtering?
  3. What about the current bug and feature labelling? How would moving from bug/new-report to bug/confirmed be covered by this new workflow?
  4. Will there be still distinction of bug vs. feature? I find bugs with affects/some and impact/medium really annoying and even more important than features with affects/many and impact/large.
  5. At which stage to label with the forgejo/ and code/ labels? I guess, at all four stages this is possible?
It really reads well and I see forward in using it. Thanks a lot for your effort! I already see improvements of the reports since we introduced the problem/enhancement workflow. Together with the new issue templates it should have enough nudging now for users to report stage/1-triage issues (instead of enhancements). I have just some questions that aren't clear to me, yet: 1. For the stage changes on normal track, all issues of a need are kept open until a PR closes all of them? 2. What about issues that are triaged and not considered for continuation (you gave nice sample texts), maybe it is still worth to have labels for them for easier filtering? 3. What about the current bug and feature labelling? How would moving from bug/new-report to bug/confirmed be covered by this new workflow? 4. Will there be still distinction of bug vs. feature? I find bugs with affects/some and impact/medium really annoying and even more important than features with affects/many and impact/large. 5. At which stage to label with the forgejo/ and code/ labels? I guess, at all four stages this is possible?
Author
Owner
Copy link

For the stage changes on normal track, all issues of a need are kept open until a PR closes all of them?

I envision that the raw user problems (triage stage issues) are closed after they have been reviewed. Once the input can be said to have influenced something, it can be closed. However, I suppose that we need to try. They are basically raw input data and could also help to learn about other things. For example, a user complaining about a specific problem might still give some interesting data for an entirely unrelated thing.

Basically, I hope that we'll evolve good tools on how to classify the user reports, and that simply by reading about user problems with more elaboration we get a better understanding of what users are trying to achieve with Forgejo.

What about issues that are triaged and not considered for continuation (you gave nice sample texts), maybe it is still worth to have labels for them for easier filtering?

There are some user research labels and it would be nice to keep classifying them. However, I think that there is probably a lot that can simply be closed. As said above, I think that the efficient analysis will be a iterative process.

Will there be still distinction of bug vs. feature? I find bugs with affects/some and impact/medium really annoying and even more important than features with affects/many and impact/large.

One of the goals described in my talk is that the distinction between bugs and features should be skipped, simply because it is not clear. Users are facing problems. Some of them are critical, some less so. Some are easy to implement, others are not. It's more complex than bug vs feature, and forcing issues into such a classification is a bad idea IMHO.

Do you have examples about such a bug that is more important than a feature? I think the only thing that is added on top of that is implementation complexity, and it is natural that more complex things are less likely to be picked up than trivial ones.

What about the current bug and feature labelling? How would moving from bug/new-report to bug/confirmed be covered by this new workflow?

If the workflow works out, I would archive the existing labels and try to convert as much as possible from the old ones, similar to how there are only a few issues with the original "bug" label.

I hope that we can get rid of the bug template and consequently also of the issues that still have their labels. So instead of moving from bug/new-report to bug/confirmed, the issues would move from stage/1-triage to stage/4-implementation.

At which stage to label with the forgejo/ and code/ labels? I guess, at all four stages this is possible?

Yes, basically at every stage. This will also be subject to iteration to see which labels are useful and which are not. For example, we currently have the forgejo/ui label added to a lot of stuff, including things that require backend fixes. I don't know how useful the granular classification is. I find it useful to cluster for two reasons:

  • area of responsibility, e.g. "security features" so the respective team can filter for them
  • related things, so that you can take a look at other issues (e.g. with project management) and can plan them accordingly

The latter is mostly achieved with the user research labels. The former is relevant to all Forgejo contributors and it probably makes sense to revisit the labels we have and how they are added from time to time, to see if everyone is happy with the current classification.

> For the stage changes on normal track, all issues of a need are kept open until a PR closes all of them? I envision that the raw user problems (triage stage issues) are closed after they have been reviewed. Once the input can be said to have influenced something, it can be closed. However, I suppose that we need to try. They are basically raw input data and could also help to learn about other things. For example, a user complaining about a specific problem might still give some interesting data for an entirely unrelated thing. Basically, I hope that we'll evolve good tools on how to classify the user reports, and that simply by reading about user problems with more elaboration we get a better understanding of what users are trying to achieve with Forgejo. > What about issues that are triaged and not considered for continuation (you gave nice sample texts), maybe it is still worth to have labels for them for easier filtering? There are some user research labels and it would be nice to keep classifying them. However, I think that there is probably a lot that can simply be closed. As said above, I think that the efficient analysis will be a iterative process. > Will there be still distinction of bug vs. feature? I find bugs with affects/some and impact/medium really annoying and even more important than features with affects/many and impact/large. One of the goals described in my talk is that the distinction between bugs and features should be skipped, simply because it is not clear. Users are facing problems. Some of them are critical, some less so. Some are easy to implement, others are not. It's more complex than bug vs feature, and forcing issues into such a classification is a bad idea IMHO. Do you have examples about such a bug that is more important than a feature? I think the only thing that is added on top of that is implementation complexity, and it is natural that more complex things are less likely to be picked up than trivial ones. > What about the current bug and feature labelling? How would moving from bug/new-report to bug/confirmed be covered by this new workflow? If the workflow works out, I would archive the existing labels and try to convert as much as possible from the old ones, similar to how there are only a few issues with the original "bug" label. I hope that we can get rid of the bug template and consequently also of the issues that still have their labels. So instead of moving from bug/new-report to bug/confirmed, the issues would move from stage/1-triage to stage/4-implementation. > At which stage to label with the forgejo/ and code/ labels? I guess, at all four stages this is possible? Yes, basically at every stage. This will also be subject to iteration to see which labels are useful and which are not. For example, we currently have the forgejo/ui label added to a lot of stuff, including things that require backend fixes. I don't know how useful the granular classification is. I find it useful to cluster for two reasons: * area of responsibility, e.g. "security features" so the respective team can filter for them * related things, so that you can take a look at other issues (e.g. with project management) and can plan them accordingly The latter is mostly achieved with the user research labels. The former is relevant to all Forgejo contributors and it probably makes sense to revisit the labels we have and how they are added from time to time, to see if everyone is happy with the current classification.
Member
Copy link

@fnetX wrote in #1983 (comment):

I think it would be worth mentioning the situations where stages do not need to be iterated through explicitly

Do you have a suggestion on how you'd like to do it?

Maybe the text you added about using the same issue and changing the labels is enough (I guess it makes it obvious that you can skip also going through some of the labels).

@fnetX wrote in https://codeberg.org/forgejo/docs/pulls/1983#issuecomment-15965714: > > I think it would be worth mentioning the situations where stages do not need to be iterated through explicitly > > Do you have a suggestion on how you'd like to do it? Maybe the text you added about using the same issue and changing the labels is enough (I guess it makes it obvious that you can skip also going through some of the labels).

Thanks for your detailed answer.

@fnetX wrote in #1983 (comment):

For the stage changes on normal track, all issues of a need are kept open until a PR closes all of them?

I envision that the raw user problems (triage stage issues) are closed after they have been reviewed. Once the input can be said to have influenced something, it can be closed.

Related, what I was worrying about: forgejo/forgejo#10497 didn't get closed after three months. Not a big deal, but could become messy at the same time ;) Let's see how it evolves.

Do you have examples about such a bug that is more important than a feature?

E.g., I think of 404s in the UI. Of course, the impact is not huge. But if you encounter them, they are annoying. I find personally the fixes for them more important then new features currently. They potentially affect only few people (e.g., people trying to do an action on archived repos, see forgejo/forgejo#12773). The bug/confirmed gives still some importance to them. In general this applies to many UI issues.

Thinking of your new labels, maybe indeed I'd reclassify quite some impact/small and impact/medium issues to impact/high, because till now, they included the requirement on number of affected people. Without, a bug that affects only one person can still get the impact/high label.

Thanks for your detailed answer. @fnetX wrote in https://codeberg.org/forgejo/docs/pulls/1983#issuecomment-15986600: > > For the stage changes on normal track, all issues of a need are kept open until a PR closes all of them? > > I envision that the raw user problems (triage stage issues) are closed after they have been reviewed. Once the input can be said to have influenced something, it can be closed. Related, what I was worrying about: https://codeberg.org/forgejo/forgejo/issues/10497 didn't get closed after three months. Not a big deal, but could become messy at the same time ;) Let's see how it evolves. > Do you have examples about such a bug that is more important than a feature? E.g., I think of 404s in the UI. Of course, the impact is not huge. But if you encounter them, they are annoying. I find personally the fixes for them more important then new features currently. They potentially affect only few people (e.g., people trying to do an action on archived repos, see https://codeberg.org/forgejo/forgejo/pulls/12773). The bug/confirmed gives still some importance to them. In general this applies to many UI issues. Thinking of your new labels, maybe indeed I'd reclassify quite some `impact/small` and `impact/medium` issues to `impact/high`, because till now, they included the requirement on number of affected people. Without, a bug that affects only one person can still get the `impact/high` label.
fnetX force-pushed fnetx/issue_workflow from 7d17336009
All checks were successful
pr / preview (pull_request_target) Successful in 4m14s
to 3d15eedc19
All checks were successful
pr / preview (pull_request_target) Successful in 2m53s
2026年06月01日 16:13:45 +02:00 Compare
@ -0,0 +44,4 @@
### Stage 2: Research
- **Who can create:** Forgejo maintainers and contributors.
Member
Copy link

Is "maintainers" intended to be "mergers"? I don't know who this is referring to otherwise, and why it is separate from contributors.

Is "maintainers" intended to be "mergers"? I don't know who this is referring to otherwise, and why it is separate from contributors.
Author
Owner
Copy link

Hmm ... I think the classification I wanted to make is between existing contributors and interested new ones. For example, I imagined that more people can move through the process (research / design), but that the final "this is ready for implementation" is done by a smaller team. However, we don't really have a structure that fits well. The contributors team is very large and lax, restricting to mergers would create a bottleneck.

I'll push a change, maybe that is better?

Hmm ... I think the classification I wanted to make is between existing contributors and interested new ones. For example, I imagined that more people can move through the process (research / design), but that the final "this is ready for implementation" is done by a smaller team. However, we don't really have a structure that fits well. The contributors team is very large and lax, restricting to mergers would create a bottleneck. I'll push a change, maybe that is better?
Member
Copy link

Sure, that's clearer to me. 👍

Sure, that's clearer to me. 👍
mfenniak marked this conversation as resolved 
It shouldn't be too strict, but ideally, only 'trusted' people create the final 'this is ready for implementation' stage
adjust snippets
Some checks failed
pr / preview (pull_request_target) Failing after 1m14s
30b3ad23a2
@ -0,0 +69,4 @@
### Stage 4: Implementation
- **Who can create:** Members of at least one elected Forgejo team.
Member
Copy link

Although maintainers is maybe too unspecific, I think that now this is too restrictive. Not all advanced Forgejo contributors are formally in an elected team, e.g., aahlenst. Maybe a wording like "experienced" or "advanced" Forgejo contributors? Or: just Forgejo developers?

Although maintainers is maybe too unspecific, I think that now this is too restrictive. Not all advanced Forgejo contributors are formally in an elected team, e.g., aahlenst. Maybe a wording like "experienced" or "advanced" Forgejo contributors? Or: just Forgejo developers?
Member
Copy link

I think that you raise a good point because there are reasonable times when a contributor can identify that an issue is non-controversial and ready for implementation, particularly in bug fixes. But wording like "experienced" or "advanced" is pretty vague, and that would leaving people unsure if they qualify, and possibly unlikely to perform this kind of labelling because of that uncertainty.

Because I think we should tend towards trusting people's judgment, and tend towards more people doing more work with fewer bottlenecks... if it was explained in detail it would be something like: "Forgejo contributors who judge that an issue is ready for this stage, deferring judgment to related team members if they have reason to doubt." But I'm not sure that's a very succinct or clear explanation either. 🤔

"elected" is also a bit of a strange word to use here, since that doesn't quite match the team membership process, which lacks an election. Perhaps clearer here would just be to enumerate specific teams in the governance do that would be relevant to making these decisions (if unclear), which could be Accessibility, UI, Helm, DevOps, Mergers, Localization, Releases, Security... maybe that's it?

I think that you raise a good point because there are reasonable times when a contributor can identify that an issue is non-controversial and ready for implementation, particularly in bug fixes. But wording like "experienced" or "advanced" is pretty vague, and that would leaving people unsure if they qualify, and possibly unlikely to perform this kind of labelling because of that uncertainty. Because I think we should tend towards trusting people's judgment, and tend towards more people doing more work with fewer bottlenecks... if it was explained in detail it would be something like: "Forgejo contributors who judge that an issue is ready for this stage, deferring judgment to related team members if they have reason to doubt." But I'm not sure that's a very succinct or clear explanation either. 🤔 "elected" is also a bit of a strange word to use here, since that doesn't quite match the team membership process, which lacks an election. Perhaps clearer here would just be to enumerate specific teams in the governance do that would be relevant to making these decisions (if unclear), which could be Accessibility, UI, Helm, DevOps, Mergers, Localization, Releases, Security... maybe that's it?
Author
Owner
Copy link

I do not want such governance questions to block the workflow changes itself. Maybe I'll reword to "Advanced" or similar.

Maybe "Members of the Contributors team" would be enough here, though.

I do not want such governance questions to block the workflow changes itself. Maybe I'll reword to "Advanced" or similar. Maybe "Members of the Contributors team" would be enough here, though.
Member
Copy link

"Members of the Contributors team" is fine with me. We can have a future discussion based upon real-world things that have happened, if necessary.

"Members of the Contributors team" is fine with me. We can have a future discussion based upon real-world things that have happened, if necessary.
fnetX marked this conversation as resolved

@fnetX to make the CI running again, please rebase to/merge next.

@fnetX to make the CI running again, please rebase to/merge next.
fnetX force-pushed fnetx/issue_workflow from 44cf625bc8 to 9e340fd823
Some checks failed
pr / preview (pull_request) Failing after 36s
2026年06月11日 15:13:49 +02:00 Compare
floss4good left a comment
Copy link

Also, please note that DISCUSSIONS.md needs some updates:

title: Bugs, features and discussions
license: 'CC-BY-SA-4.0'
---
The [Forgejo issue tracker](https://codeberg.org/forgejo/forgejo/issues) is where **bugs** should be reported and **features** requested.
Also, please note that _DISCUSSIONS.md_ needs some updates: https://codeberg.org/forgejo/docs/src/commit/64fe34712f456d92109e125d5632b5508518400d/docs/contributor/DISCUSSIONS.md?display=source#L2-L6
@ -10,3 +10,3 @@
- For everyone involved
- [Code of Conduct](./coc/)
- [Bugs, enhancement ideas and development roadmap](https://codeberg.org/forgejo/forgejo/issues)
- [Issue, research, design and implementation workflow](./issue_workflow/)

I think this caption should be aligned a little bit with the title from issue_workflow.md.
Maybe something like:

Issue tracker: reporting problems, research, design and implementation workflow

Although implementation should probably be removed because the workflow does not cover the actual implementation/development part.

I think this caption should be aligned a little bit with the title from _issue_workflow.md_. Maybe something like: > Issue tracker: reporting problems, research, design and implementation workflow Although `implementation` should probably be removed because the workflow does not cover the actual implementation/development part.
Author
Owner
Copy link

you are right. The workflow to implementation basically, but it can be stripped.

you are right. The workflow to implementation basically, but it can be stripped.
fnetX marked this conversation as resolved
@ -0,0 +25,4 @@
Issue tracking is separated into 4 stages.
Issues can be "converted" between stages:

What should happen with the description - which has a standard format, based on the corresponding template - when an issue is "converted" by updating the stage/ label?
I already find it awkward to open issues labeled as enhancement/feature and to find out that they were filled in using the problem template.

What should happen with the description - which has a standard format, based on the corresponding template - when an issue is "_converted_" by updating the `stage/` label? I already find it awkward to open issues labeled as `enhancement/feature` and to find out that they were filled in using the `problem` template.
Author
Owner
Copy link

My idea was that for simple cases, there is no need to update the description, because it is clear enough to anyone visiting it.

For complex cases, I envision to create new issues so that the previous discussion can be summarized and the developer picking up a task does not need to read a backlog of year-long discussions from user's explaining their problem to people arguing about the design.

I'll try to spell this out.

My idea was that for simple cases, there is no need to update the description, because it is clear enough to anyone visiting it. For complex cases, I envision to create new issues so that the previous discussion can be summarized and the developer picking up a task does not need to read a backlog of year-long discussions from user's explaining their problem to people arguing about the design. I'll try to spell this out.
@ -0,0 +27,4 @@
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.

exhausted → exhausting

`exhausted` → `exhausting`
fnetX marked this conversation as resolved
@ -0,0 +42,4 @@
- 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-4/implementation → stage-4 (implementation) (for consistency)

`stage-4/implementation` → `stage-4 (implementation)` (for consistency)
Author
Owner
Copy link

I'm converting to the actual name of the labels

I'm converting to the actual name of the labels
fnetX marked this conversation as resolved
@ -0,0 +49,4 @@
- **Who can create:** Forgejo contributors.
- **Responsible for these issues:** 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?

thinking out loud:
Maybe expect it to work would be better?!
If so, How is this solved should be probably also updated.

_thinking out loud:_ Maybe `expect it to work` would be better?! If so, `How is this solved` should be probably also updated.
Author
Owner
Copy link

no real opinion here, updating ...

no real opinion here, updating ...
fnetX marked this conversation as resolved
@ -0,0 +53,4 @@
- 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

For consistency, maybe this should be close research and stage-1 (triaging) issues (or simply related issues).

For consistency, maybe this should be `close research and stage-1 (triaging) issues` (or simply `related issues`).
Author
Owner
Copy link

also changing to label names

also changing to label names
@ -0,0 +54,4 @@
- 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

I find this guideline a little bit strange or not clear, taking into account that responsible for these issues is in particular the user research team.

I find this guideline a little bit strange or not clear, taking into account that responsible for these issues is _in particular the user research team_.
Author
Owner
Copy link

please check if this is better ...

since I hope that everyone participates in this stage, I imagined people can ping the user research team for cases where they need help

please check if this is better ... since I hope that everyone participates in this stage, I imagined people can ping the user research team for cases where they need help
@ -0,0 +65,4 @@
- **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

(sort of) thinking out loud:
At a first read I asked myself what results and where should be documented; after reading the goal from 'Stage 4: Implementation' - Document changes that need to be implemented. [...] - my questions were somehow answered but in the same time now I think that the and document the results part is kind of included in convert to stage-4 (implementation).

_(sort of) thinking out loud:_ At a first read I asked myself what results and where should be documented; after reading the goal from 'Stage 4: Implementation' - _Document changes that need to be implemented. [...]_ - my questions were somehow answered but in the same time now I think that the `and document the results` part is kind of included in `convert to stage-4 (implementation)`.
@ -0,0 +82,4 @@
- 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

Some US/UK consistency issue:

US UK
analyzed analysed
behavior behaviour

I don't want to start again the discussion about American English vs. British English, but I think we should either keep analyzed and change behaviour to behavior or keep behaviour and change analyzed to analysed.

Some US/UK consistency issue: | US | UK | |----|----| | **analyzed** | analysed | | behavior | **behaviour** | I don't want to start again the [discussion](https://codeberg.org/forgejo/governance/pulls/381#issuecomment-11421439) about American English vs. British English, but I think we should either keep `analyzed` and change `behaviour` to `behavior` or keep `behaviour` and change `analyzed` to `analysed`.
fnetX marked this conversation as resolved
@ -0,0 +101,4 @@
Outdated problems (e.g. when Forgejo changed and the user experience is likely different anyway):
> 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.

Small consistency issue: We'll close while below is used I am closing.

Small consistency _issue_: `We'll close` while below is used `I am closing`.
Author
Owner
Copy link

The next snippets don't really need to be consistent. Ideally, people tune them for their own style so they look more personal ...

The next snippets don't really need to be consistent. Ideally, people tune them for their own style so they look more personal ...
fnetX marked this conversation as resolved
fnetX force-pushed fnetx/issue_workflow from 9e340fd823
Some checks failed
pr / preview (pull_request) Failing after 36s
to a95a1b0d92
Some checks failed
pr / preview (pull_request) Failing after 30s
2026年07月01日 22:57:57 +02:00 Compare
Author
Owner
Copy link

@floss4good
a95a1b0d92 are the changes over the last version. I'll look at the last open threads ASAP.

@floss4good https://codeberg.org/forgejo/docs/commit/a95a1b0d9222877103abb2a2bf5814f32433f9c8 are the changes over the last version. I'll look at the last open threads ASAP.
Some checks failed
pr / preview (pull_request) Failing after 30s
Required
Details
This pull request doesn't have enough approvals yet. 0 of 1 approvals granted.
This branch is out-of-date with the base branch
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin +refs/pull/1983/head:fnetx/issue_workflow
git switch fnetx/issue_workflow
Sign in to join this conversation.
No reviewers
Labels
Clear labels
404
Broken links or missing content
backport/v1.19
Changes which should be backported to the v1.19 docs

Archived

backport/v1.20
Changes which should be backported to the v1.20 docs

Archived

backport/v1.21
Changes which should be backported to the v1.21 docs

Archived

backport/v10.0
Automated backport to v10.0

Archived

backport/v11.0
Automated backport to v11.0
backport/v12.0
Automated backport to v12.0

Archived

backport/v13.0
Automated backport to v13.0

Archived

backport/v14.0
Automated backport to v14.0

Archived

backport/v15.0
Automated backport to v15.0
backport/v16.0
Automated backport to v16.0
backport/v7.0
Automated backport to the v7.0 docs

Archived

backport/v8.0
Automated backport to the v8.0 docs

Archived

backport/v9.0
Automated backport to the v9.0 docs

Archived

good first issue
This issue is suitable for "drive-by contributors" wanting to contribute for the first time, and fixing it should be straightforward.
meta
Tooling and processes for maintaining the docs
new docs
Content to be added to the documentation

Archived

User research - Accessibility
Requires input about accessibility features, likely involves user testing.
User research - Blocked
Do not pick as-is! We are happy if you can help, but please coordinate with ongoing redesign in this area.
User research - Community
Community features, such as discovering other people's work or otherwise feeling welcome on a Forgejo instance.
User research - Config (instance)
Instance-wide configuration, authentication and other admin-only needs.
User research - Errors
How to deal with errors in the application and write helpful error messages.
User research - Filters
How filter and search is being worked with.
User research - Future backlog
The issue might be inspiring for future design work.
User research - Git workflow
AGit, fork-based and new Git workflow, PR creation etc
User research - Labels
Active research about Labels
User research - Moderation
Moderation Featuers for Admins are undergoing active User Research
User research - Needs input
Use this label to let the User Research team know their input is requested.
User research - Notifications/Dashboard
Research on how users should know what to do next.
User research - Rendering
Text rendering, markup languages etc
User research - Repo creation
Active research about the New Repo dialog.
User research - Repo units
The repo sections, disabling them and the "Add more" button.
User research - Security
User research - Settings (in-app)
How to structure in-app settings in the future?
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
7 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
forgejo/docs!1983
Reference in a new issue
forgejo/docs
No description provided.
Delete branch "fnetx/issue_workflow"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?