[Repo alignment] Fix labels

pbokoc commented

2026-05-05 10:39:30 +00:00

Owner

The labels in our docs organization repositories are currently a massive mess. We need to come up with a common set of useful labels that we want to use. To do that, we first need to figure out what exactly we want to track (the fewer things the better, and they should be self-explanatory as much as possible), and then set every repo in the docs organization to use them.

👍 1

pbokoc added this to the (deleted) project

2026-05-05 10:39:46 +00:00

pbokoc referenced this issue

2026-05-05 10:43:33 +00:00

Repository alignment #18

pbokoc commented

2026-05-05 13:36:23 +00:00

Author

Owner

Here is the current org-level set of labels for https://forge.fedoraproject.org/docs.

The format is scope/item and labels within a certain scope are mutually exclusive. So, for example, if an issue has a ?/needs changes, it can't also have ?/needs triage. A scope can also be empty, which means those items can be used on top of anything else.

good first issue
help wanted
?/needs changes
?/needs reporter feedback
?/needs triage
?/needs vote
scope/bug
scope/improvement
scope/new
scope/approved
state/blocked
state/duplicate
state/invalid
state/wontfix

Here is the current org-level set of labels for https://forge.fedoraproject.org/docs. The format is `scope/item` and labels within a certain scope are mutually exclusive. So, for example, if an issue has a `?/needs changes`, it can't also have `?/needs triage`. A scope can also be empty, which means those items can be used on top of anything else. * good first issue * help wanted * ?/needs changes * ?/needs reporter feedback * ?/needs triage * ?/needs vote * scope/bug * scope/improvement * scope/new * scope/approved * state/blocked * state/duplicate * state/invalid * state/wontfix

pbokoc commented

2026-05-05 13:43:05 +00:00

Author

Owner

Some thoughts:

needs triage is only useful if it's automatically applied to any new issue. It tells us that it's new and hasn't been seen by anyone from the team, so it needs attention - but we can't expect issue reporters to consistently apply it by hand, and I don't think forgejo can do it automatically. There definitely isn't a way to set that up in the settings. Maybe a runner could do it?
The whole scope/ group doesn't seem particularly useful to me. Do we really care if something is a bug fix vs improvement?
state/ is kinda missing a complete label, though I suppose an issue being closed without any other state present implies that.
We should have a "meeting topic request".

Some thoughts: * `needs triage` is only useful if it's automatically applied to any new issue. It tells us that it's new and hasn't been seen by anyone from the team, so it needs attention - but we can't expect issue reporters to consistently apply it by hand, and I don't think forgejo can do it automatically. There definitely isn't a way to set that up in the settings. Maybe a runner could do it? * The whole `scope/` group doesn't seem particularly useful to me. Do we really care if something is a bug fix vs improvement? * `state/` is kinda missing a `complete` label, though I suppose an issue being closed without any other state present implies that. * We should have a "meeting topic request".

pbokoc commented

2026-05-05 13:46:08 +00:00

Author

Owner

AIs from the docs meeting on May 5 2026:

@pboy @pbokoc Write a clear proposal for issue labels and update Ticket #40 with the proposal, so it is clear to all Docs Team members what is being voted on. Do this at least 48 hours before the next Docs Team meeting on 19 May 2026.

@pbokoc Create a first-draft version of issue label howto for Fedora Docs team docs repo, prepare to share on 19 May 2026 team meeting

There's also this in our current docs, we'll need to completely rewrite it when we come up with a set of labels for the org: https://docs.fedoraproject.org/en-US/fedora-docs/organizational/workflow/

AIs from the docs meeting on May 5 2026: @pboy @pbokoc Write a clear proposal for issue labels and update Ticket #40 with the proposal, so it is clear to all Docs Team members what is being voted on. Do this at least 48 hours before the next Docs Team meeting on 19 May 2026. @pbokoc Create a first-draft version of issue label howto for Fedora Docs team docs repo, prepare to share on 19 May 2026 team meeting --- There's also this in our current docs, we'll need to completely rewrite it when we come up with a set of labels for the org: https://docs.fedoraproject.org/en-US/fedora-docs/organizational/workflow/

👍 1

pbokoc modified the project from (deleted) to (deleted)

2026-05-05 13:46:16 +00:00

cstrauf referenced this issue from docs/team-docs

2026-05-05 13:47:56 +00:00

Update labels #56

cstrauf commented

2026-05-05 13:48:25 +00:00

Member

Added docs/team-docs#56 for https://docs.fedoraproject.org/en-US/fedora-docs/organizational/workflow/

Added https://forge.fedoraproject.org/docs/team-docs/issues/56 for https://docs.fedoraproject.org/en-US/fedora-docs/organizational/workflow/

👍 1

cstrauf added a new dependency

2026-05-05 13:51:00 +00:00

docs/team-docs#56 - Update labels

pbokoc modified the project from (deleted) to (deleted)

2026-05-05 13:51:18 +00:00

pbokoc added a new dependency

2026-05-05 13:58:02 +00:00

#18 Repository alignment

jflory7 commented

2026-05-05 14:17:15 +00:00

Owner

Discussed in 2026-05-05 Docs Team meeting.

The team engaged in a deep discussion about how to organize issue labels. We agreed to focus on standardizing an organization-wide label set across the docs/* namespace to make cross-repository work easier, while leaving repo-level labels up to individual maintainers. A formal vote to ratify a clear proposal for these labels will be held at the May 19 team meeting.

Follow-up Items:

Action: @pboy and @pbokoc to write a clear proposal for issue labels and update this ticket with the proposal at least 48 hours before the May 19 meeting.
Action: @pbokoc to create a first-draft version of an issue label how-to guide for the Docs Team repository.
Formal Decision: !agreed As a team, we should focus this conversation about _organization-wide issue labels_ since it impacts all repos and contributors working under the forge.fp.o/docs organization. We prefer to not get in the business of standardizing repo-level labels, as we believe individual maintainers can decide whether greater specificity is needed beyond the organization-wide labels.
Formal Decision: !agreed We are putting a team vote requirement on this ticket. All team members are encouraged to share feedback in Ticket #40. On the next team meeting on 19 May 2026, we will record a final vote, ratify, and move on. Docs Team leads will also work on a clear proposal for voting on, and also writing meta docs on the proposed labeling system.

_Discussed in [2026-05-05 Docs Team meeting](https://discussion.fedoraproject.org/t/fedora-docs-team-meeting-2026-05-05-organization-wide-issue-labels-workflow-updates/190491)_. --- The team engaged in a deep discussion about how to organize issue labels. We agreed to focus on standardizing an organization-wide label set across the `docs/*` namespace to make cross-repository work easier, while leaving repo-level labels up to individual maintainers. A formal vote to ratify a clear proposal for these labels will be held at the May 19 team meeting. **Follow-up Items:** * **Action:** @pboy and @pbokoc to write a clear proposal for issue labels and update this ticket with the proposal at least 48 hours before the May 19 meeting. * **Action:** @pbokoc to create a first-draft version of an issue label how-to guide for the Docs Team repository. * **Formal Decision:** `!agreed As a team, we should focus this conversation about _organization-wide issue labels_ since it impacts all repos and contributors working under the forge.fp.o/docs organization. We prefer to not get in the business of standardizing repo-level labels, as we believe individual maintainers can decide whether greater specificity is needed beyond the organization-wide labels.` * **Formal Decision:** `!agreed We are putting a team vote requirement on this ticket. All team members are encouraged to share feedback in Ticket #40. On the next team meeting on 19 May 2026, we will record a final vote, ratify, and move on. Docs Team leads will also work on a clear proposal for voting on, and also writing meta docs on the proposed labeling system.`

jflory7 added this to the 2026 Q2 Team Goals milestone

2026-05-05 14:17:37 +00:00

jflory7 added the due date 2026-05-19

2026-05-05 14:17:43 +00:00

jflory7 commented

2026-05-05 14:21:49 +00:00

Owner

@pbokoc wrote in #40 (comment):

* `needs triage` is only useful if it's automatically applied to any new issue. It tells us that it's new and hasn't been seen by anyone from the team, so it needs attention - but we can't expect issue reporters to consistently apply it by hand, and I don't think forgejo can do it automatically. There definitely isn't a way to set that up in the settings. Maybe a runner could do it?

Our issue templates automatically add this label to new issues, at least on the Tickets repo. I think it is worth keeping for use with the issue templates.

* The whole `scope/` group doesn't seem particularly useful to me. Do we really care if something is a bug fix vs improvement?

The concept was having a way to track/measure how much work the team does that is net-new work, improving existing work, or fixing problems. However, in practice… I don't think this is happening that often. I'm not committed to these labels. They could go.

* `state/` is kinda missing a `complete` label, though I suppose an issue being closed without any other state present implies that.

There is a state/approved label, which I guess was supposed to indicate this. But something like "done" or "complete" would make sense as a new state too, IMHO.

* We should have a "meeting topic request".

+1

@pbokoc wrote in https://forge.fedoraproject.org/docs/tickets/issues/40#issuecomment-693407: > * `needs triage` is only useful if it's automatically applied to any new issue. It tells us that it's new and hasn't been seen by anyone from the team, so it needs attention - but we can't expect issue reporters to consistently apply it by hand, and I don't think forgejo can do it automatically. There definitely isn't a way to set that up in the settings. Maybe a runner could do it? Our issue templates automatically add this label to new issues, at least on the Tickets repo. I think it is worth keeping for use with the issue templates. > * The whole `scope/` group doesn't seem particularly useful to me. Do we really care if something is a bug fix vs improvement? The concept was having a way to track/measure how much work the team does that is net-new work, improving existing work, or fixing problems. However, in practice… I don't think this is happening that often. I'm not committed to these labels. They could go. > * `state/` is kinda missing a `complete` label, though I suppose an issue being closed without any other state present implies that. There is a `state/approved` label, which I guess was supposed to indicate this. But something like "done" or "complete" would make sense as a new state too, IMHO. > * We should have a "meeting topic request". +1

pbokoc modified the project from (deleted) to (deleted)

2026-05-05 15:06:54 +00:00

a-moor commented

2026-05-05 16:59:05 +00:00

I would like to propose a clearer and more beginner-friendly label structure/framework for the repository. The goal is to make issues easier to understand, faster to triage, and more approachable for new contributors.

Proposal: Issue Label Structure

The proposed structure separates four different questions that an issue can answer: what kind of work it is, how much effort it may require, how important it is for the team, and where it currently stands in the workflow. This makes the labeling system easier to read and helps contributors quickly understand how to approach an issue.

1. Type

This category describes what kind of work an issue is about.

Text
Code
Infrastructure

2. Effort

This category describes how much effort an issue is likely to require.

low
medium
high

3. Priority

low
normal
high

4. Status

This category describes where the issue currently is in the workflow.

Needs Info
Needs Decision
Needs Discussion
Todo
In Progress
Needs Help
Blocked
Needs Review
In Review
Needs Changes
Needs Testing
In Testing
Done
Duplicate
Won't be Done

Why this structure works

This structure separates four different questions very clearly:

Type: What kind of task is this?
Effort: How big or difficult is it?
Priority: How important is it?
Status: What is the current state of the issue?

That makes the system easier to understand for new contributors, while still being detailed enough for maintainers to manage the workflow effectively.

Why this is better than a mixed label set

In a mixed label system, labels often describe several things at once, which makes them harder to interpret. By separating type, effort, priority and status, each label has one clear purpose.

For example:

Type:Text tells contributors that the issue is about writing or editing content.
Effor:high tells them that the issue is likely more demanding.
Priority:low tells how important this issue is.
Status:Needs Review tells them that the work is ready and waiting for review.

Suggested workflow meaning

The workflow is step-based and keeps each issue’s current state clear at a glance: from needing more information, discussion, or a decision, to being ready, in progress, under review, tested, and finally done or closed with a clear outcome.

The status labels can be understood as follows:

Needs Info: More information is needed before work can continue.
Needs Decision: A decision has to be made first.
Needs Discussion: The topic should be discussed before work starts.
Todo: The issue is ready to be worked on.
In Progress: Someone is currently working on it.
Needs Help: Extra help is needed.
Blocked: Work cannot continue right now.
Needs Review: The work is finished and ready for review.
In Review: The issue is currently being reviewed.
Needs Changes: Review is done, but changes are required.
Needs Testing: The work is ready for testing.
In Testing: Testing is currently happening.
Done: The issue is completed.
Duplicate: The issue already exists elsewhere.
Won't be Done: The issue will not be pursued further.

For example, an issue may start at Needs info, move to Todo, then In Progress, then Needs Review, and finally Done; if something is missing or unclear, it can move to Needs Discussion or Needs Decision instead. With this setup, it is always possible to see whether an issue is waiting for input, actively being worked on, under review, blocked, or already finished.

Closing note

Overall, this structure should lower the entry barrier for new contributors while still giving maintainers a practical and flexible workflow. It also keeps the labels readable, consistent, and easier to maintain over time.

I would like to propose a clearer and more beginner-friendly label structure/framework for the repository. The goal is to make issues easier to understand, faster to triage, and more approachable for new contributors. ## Proposal: Issue Label Structure The proposed structure separates four different questions that an issue can answer: **what kind of work it is**, **how much effort it may require**, **how important it is for the team**, and **where it currently stands in the workflow**. This makes the labeling system easier to read and helps contributors quickly understand how to approach an issue. ## 1. Type This category describes **what kind of work** an issue is about. - `Text` - `Code` - `Infrastructure` ## 2. Effort This category describes **how much effort** an issue is likely to require. - `low` - `medium` - `high` ## 3. Priority - `low` - `normal` - `high` ## 4. Status This category describes **where the issue currently is in the workflow**. - `Needs Info` - `Needs Decision` - `Needs Discussion` - `Todo` - `In Progress` - `Needs Help` - `Blocked` - `Needs Review` - `In Review` - `Needs Changes` - `Needs Testing` - `In Testing` - `Done` - `Duplicate` - `Won't be Done` ## Why this structure works This structure separates four different questions very clearly: - **Type**: What kind of task is this? - **Effort**: How big or difficult is it? - **Priority**: How important is it? - **Status**: What is the current state of the issue? That makes the system easier to understand for new contributors, while still being detailed enough for maintainers to manage the workflow effectively. ## Why this is better than a mixed label set In a mixed label system, labels often describe several things at once, which makes them harder to interpret. By separating type, effort, priority and status, each label has one clear purpose. For example: - `Type:Text` tells contributors that the issue is about writing or editing content. - `Effor:high` tells them that the issue is likely more demanding. - `Priority:low` tells how important this issue is. - `Status:Needs Review` tells them that the work is ready and waiting for review. ## Suggested workflow meaning >The workflow is step-based and keeps each issue’s current state clear at a glance: from needing more information, discussion, or a decision, to being ready, in progress, under review, tested, and finally done or closed with a clear outcome. The status labels can be understood as follows: - `Needs Info`: More information is needed before work can continue. - `Needs Decision`: A decision has to be made first. - `Needs Discussion`: The topic should be discussed before work starts. - `Todo`: The issue is ready to be worked on. - `In Progress`: Someone is currently working on it. - `Needs Help`: Extra help is needed. - `Blocked`: Work cannot continue right now. - `Needs Review`: The work is finished and ready for review. - `In Review`: The issue is currently being reviewed. - `Needs Changes`: Review is done, but changes are required. - `Needs Testing`: The work is ready for testing. - `In Testing`: Testing is currently happening. - `Done`: The issue is completed. - `Duplicate`: The issue already exists elsewhere. - `Won't be Done`: The issue will not be pursued further. For example, an issue may start at `Needs info`, move to `Todo`, then `In Progress`, then `Needs Review`, and finally `Done`; if something is missing or unclear, it can move to `Needs Discussion` or `Needs Decision` instead. With this setup, it is always possible to see whether an issue is waiting for input, actively being worked on, under review, blocked, or already finished. ## Closing note Overall, this structure should lower the entry barrier for new contributors while still giving maintainers a practical and flexible workflow. It also keeps the labels readable, consistent, and easier to maintain over time.

❤️ 3

korora commented

2026-05-06 16:00:49 +00:00

Member

Reading through this, I really like @a-moor's suggestion for tags. it provides a lean, clean tag system that is logical and makes sense.

+1 for this suggestion

Reading through this, I really like @a-moor's suggestion for tags. it provides a lean, clean tag system that is logical and makes sense. +1 for this suggestion

👍 1

mwinters commented

2026-05-06 18:09:41 +00:00

Member

I like it too, with the minor tweak that Type: Text should be Type: Content, which covers changes like images and (someday!) diagrams.

+1

I like it too, with the minor tweak that `Type: Text` should be `Type: Content`, which covers changes like images and (someday!) diagrams. +1

👍 1

pbokoc commented

2026-05-15 15:53:17 +00:00

Author

Owner

So, I don't dislike the set @a-moor came up with, but I'd like to cut down the number of possible statuses to make the ones we do use easier to find in the dropdown. Here's what I've come up with:

type/content
type/infrastructure

size/task
size/epic

effort/low
effort/medium
effort/high

priotity/low
priority/medium
priority/high

good first issue
meeting topic
needs info
needs vote
needs review
needs changes
blocked

The ones that start with the same keyword are mutually exclusive, so you can always only have one type, one size, etc. The last group can all be used at once as needed.

An epic is a set of multiple tasks, you can see an example of an epic here.

I cut all statuses that describe the ticket being closed (done, won't be done, duplicate...), because that's implied by the ticket itself being closed - it's good manners to describe why when you're closing one, anyway, so it doesn't need to be a status. I also cut a few others due to overlap, e.g. type/code and type/infra or needs discussion and needs decision are effectively the same thing. I did have to add good first issue and meeting topic because those have proven useful before.

So, I don't dislike the set @a-moor came up with, but I'd like to cut down the number of possible statuses to make the ones we do use easier to find in the dropdown. Here's what I've come up with: `type/content` `type/infrastructure` `size/task` `size/epic` `effort/low` `effort/medium` `effort/high` `priotity/low` `priority/medium` `priority/high` `good first issue` `meeting topic` `needs info` `needs vote` `needs review` `needs changes` `blocked` The ones that start with the same keyword are mutually exclusive, so you can always only have one `type`, one `size`, etc. The last group can all be used at once as needed. An `epic` is a set of multiple `task`s, you can see an example of an epic [here](https://forge.fedoraproject.org/docs/tickets/issues/18). I cut all statuses that describe the ticket being closed (`done`, `won't be done`, `duplicate`...), because that's implied by the ticket itself being closed - it's good manners to describe why when you're closing one, anyway, so it doesn't need to be a status. I also cut a few others due to overlap, e.g. `type/code` and `type/infra` or `needs discussion` and `needs decision` are effectively the same thing. I did have to add `good first issue` and `meeting topic` because those have proven useful before.

korora commented

2026-05-15 16:04:08 +00:00

Member

@pbokoc This simplification looks good to me.

+1 from me,

@pbokoc This simplification looks good to me. +1 from me,

theprogram commented

2026-05-15 16:25:13 +00:00

Member

Less is Moor,

+1 and apologies for the aweful pun.

Less is Moor, +1 and apologies for the aweful pun.

😆 2

cstrauf commented

2026-05-15 17:40:10 +00:00

Member

+1 KISS principle is good.

a-moor commented

2026-05-19 11:47:42 +00:00

Hey everyone!

I would like to add a few points and explanations to my proposal and explain the assumptions under which the labels and their categories were created and grouped.

Using Forgejo as a project management tool

Forgejo is, first and foremost, a version control tool, but it is obviously also used as a project management tool. This makes sense, since the primary goal of the Docs Team could be described as:

Add, change, improve, or delete documents describing the functionality of Fedora as a distribution and as a project.

This is probably not a SMART goal formulation, but rather a working goal to explain the following points.

Ideally, all team processes should be optimized to support this primary goal. The workflow around issues and their labeling should also be seen as one of the processes that can improve efficiency in reaching that goal.

A proper label strategy could not only help the Docs Team and contributors understand which categories an issue belongs to, but also use labels for data-driven decision-making.

Data- and KPI-driven decision-making and process optimization

Even though the label categories I proposed were not originally created with this specific strategy in mind, they can still be used to measure specific metrics and provide insights into the current and future work of the Docs Team. Specific interventions or improvements could then be tested, measured, and refined.

Simplification vs. precision

Reducing complexity in labeling should focus on lowering cognitive load. In my opinion, the most important way to achieve this goal is not necessarily to reduce the total number of labels, but to reduce the number of categories and ensure that no category contains redundant or unclear labels that lead to decision paralysis ("Should I use this label or that one?" "What does that label even mean?").

On the other hand, reducing labels, especially in the status category, can also reduce the level of insight available if the team is interested in measuring its processes, improvements, and successes.

The number of labels I have chosen for the status category should not bloat the category, but instead allow for precise decisions if the team is interested in a data- and KPI-driven approach.

To make precise decisions, the state of an issue has to be precise. It should clearly describe the current state the issue is in.

If every possible state an issue can be in is labeled and timestamped, specific KPIs could provide the following insights.

Sub-goals, KPIs, and their calculations

Below is a handful of KPIs that could be valuable for the Docs Team if the related sub-goals are considered relevant. The table is far from complete and should be seen as a pool of KPIs to brainstorm, discuss, and expand.

KPI	Meaning	Calculation	Why it matters (sub-goals)
Time to first contribution	How long it takes until someone contributes for the first time.	Date of first contribution - issue creation date	Shows how well onboarding and entry barriers work.
Time to first progress	How long it takes until an issue actually moves into active work.	Timestamp of `In Progress` - timestamp of `Todo`	Shows whether issues are clear enough to start quickly.
Blocked time	How long an issue remains blocked.	Sum of all time periods in `Blocked`	Reveals workflow friction and external dependencies.
Review time	How long an issue stays in the review process.	Timestamp of `In Review` or `Needs Review` until the next valid status	Shows whether review is a bottleneck.
Cycle time	Total time from start to completion.	Timestamp of `Done` - timestamp of `In Progress`	Measures overall delivery speed.
Throughput	How many issues are completed in a given period.	Number of `Done` issues per week or month	Shows team capacity and output trends.
Needs changes rate	How often review leads to rework.	Number of issues with `Needs Changes` / number of reviewed issues	Indicates the quality of issue descriptions and implementation.
Decision latency	How long decisions take.	Timestamp of `Needs Decision` until the next active status	Shows whether decision-making slows the workflow.
Contribution diversity	How broadly contributions are distributed across people.	Number of active contributors / number of all contributors	Shows whether contribution is spread beyond a small core group.
Priority completion rate	How well high-priority issues are completed.	Completed high-priority issues / all high-priority issues	Shows whether the team finishes what it considers most important.

Comments to @pbokoc

type/code was meant to be used for specific customization of HTML, CSS, or JS.

type/infrastructure was meant to be used for CI/CD and Forge-related topics.

size/epic is not a common word outside of agile workflows. Maybe size/project and size/task would be easier to understand for contributors without an agile project management background.

I am also not sure whether the size category is redundant with the effort category.
An issue with the label effort/medium or effort/high cannot really be a single task, from my point of view.

good first issue is also a somewhat redundant label, because it is basically effort/low.

Reducing the labels in the status category to:

meeting topic
needs info
needs vote
needs review
needs changes
blocked

would lead to missing issue states.

One example is needs review and in review. The first label provides a state in which it is clear that the issue needs a second person to review it, while the second signals that a person has already taken responsibility for the review and is actively working on it. Having both labels would make the KPI Review time possible and could, for example, lead to the conclusion that more reviewers are needed.

Summary

Using Forgejo could be an interesting way to use labels not only for description, but also for data-driven decision-making. A well-thought-out balance between a minimal number of labels and label categories, and labels that can provide valuable insights into performance and improvement opportunities, could add real value to both the team and the users of the Docs.

Hey everyone! I would like to add a few points and explanations to my proposal and explain the assumptions under which the labels and their categories were created and grouped. ## Using Forgejo as a project management tool Forgejo is, first and foremost, a version control tool, but it is obviously also used as a project management tool. This makes sense, since the **primary goal** of the Docs Team could be described as: > Add, change, improve, or delete documents describing the functionality of Fedora as a distribution and as a project. This is probably not a SMART goal formulation, but rather a working goal to explain the following points. Ideally, all team processes should be optimized to support this primary goal. The workflow around issues and their labeling should also be seen as one of the processes that can improve efficiency in reaching that goal. A proper label strategy could not only help the Docs Team and contributors understand which categories an issue belongs to, but also **use labels for data-driven decision-making**. ## Data- and KPI-driven decision-making and process optimization Even though the label categories I proposed were not originally created with this specific strategy in mind, they can still be used to measure specific metrics and provide insights into the current and future work of the Docs Team. Specific interventions or improvements could then be tested, measured, and refined. ## Simplification vs. precision Reducing complexity in labeling should focus on lowering cognitive load. In my opinion, the most important way to achieve this goal is not necessarily to reduce the total number of labels, but to reduce the number of categories and ensure that no category contains redundant or unclear labels that lead to decision paralysis ("_Should I use this label or that one?_" "_What does that label even mean?_"). On the other hand, reducing labels, especially in the **status** category, can also reduce the level of insight available if the team is interested in measuring its processes, improvements, and successes. The number of labels I have chosen for the **status** category should not bloat the category, but instead allow for precise decisions if the team is interested in a data- and KPI-driven approach. > To make precise decisions, the state of an issue has to be precise. It should clearly describe the current state the issue is in. If every possible state an issue can be in is labeled and timestamped, specific KPIs could provide the following insights. ## Sub-goals, KPIs, and their calculations Below is a handful of KPIs that could be valuable for the Docs Team if the related sub-goals are considered relevant. The table is far from complete and should be seen as a pool of KPIs to brainstorm, discuss, and expand. |KPI|Meaning|Calculation|Why it matters (sub-goals)| |---|---|---|---| |Time to first contribution|How long it takes until someone contributes for the first time.|Date of first contribution - issue creation date|Shows how well onboarding and entry barriers work.| |Time to first progress|How long it takes until an issue actually moves into active work.|Timestamp of `In Progress` - timestamp of `Todo`|Shows whether issues are clear enough to start quickly.| |Blocked time|How long an issue remains blocked.|Sum of all time periods in `Blocked`|Reveals workflow friction and external dependencies.| |Review time|How long an issue stays in the review process.|Timestamp of `In Review` or `Needs Review` until the next valid status|Shows whether review is a bottleneck.| |Cycle time|Total time from start to completion.|Timestamp of `Done` - timestamp of `In Progress`|Measures overall delivery speed.| |Throughput|How many issues are completed in a given period.|Number of `Done` issues per week or month|Shows team capacity and output trends.| |Needs changes rate|How often review leads to rework.|Number of issues with `Needs Changes` / number of reviewed issues|Indicates the quality of issue descriptions and implementation.| |Decision latency|How long decisions take.|Timestamp of `Needs Decision` until the next active status|Shows whether decision-making slows the workflow.| |Contribution diversity|How broadly contributions are distributed across people.|Number of active contributors / number of all contributors|Shows whether contribution is spread beyond a small core group.| |Priority completion rate|How well high-priority issues are completed.|Completed high-priority issues / all high-priority issues|Shows whether the team finishes what it considers most important.| ## Comments to @pbokoc `type/code` was meant to be used for specific customization of HTML, CSS, or JS. `type/infrastructure` was meant to be used for CI/CD and Forge-related topics. `size/epic` is not a common word outside of agile workflows. Maybe `size/project` and `size/task` would be easier to understand for contributors without an agile project management background. - I am also not sure whether the `size` category is redundant with the `effort` category. - An issue with the label `effort/medium` or `effort/high` cannot really be a single task, from my point of view. `good first issue` is also a somewhat redundant label, because it is basically `effort/low`. Reducing the labels in the `status` category to: - `meeting topic` - `needs info` - `needs vote` - `needs review` - `needs changes` - `blocked` would lead to missing issue states. One example is `needs review` and `in review`. The first label provides a state in which it is clear that the issue needs a second person to review it, while the second signals that a person has already taken responsibility for the review and is actively working on it. Having both labels would make the KPI `Review time` possible and could, for example, lead to the conclusion that more reviewers are needed. ## Summary Using Forgejo could be an interesting way to use labels not only for description, but also for data-driven decision-making. A well-thought-out balance between a minimal number of labels and label categories, and labels that can provide valuable insights into performance and improvement opportunities, could add real value to both the team and the users of the Docs.

pbokoc commented

2026-05-20 08:35:05 +00:00

Author

Owner

@a-moor wrote in #40 (comment):

Comments to @pbokoc

type/code was meant to be used for specific customization of HTML, CSS, or JS.

type/infrastructure was meant to be used for CI/CD and Forge-related topics.

Yeah but 99% of our issues are type/docs and it doesn't make sense to distinguish between that and non-docs, so I'm just calling everything that isn't docs "infra".

size/epic is not a common word outside of agile workflows. Maybe size/project and size/task would be easier to understand for contributors without an agile project management background.

Right, I think I'll just drop the whole size category. It's somewhat indicated by an issue having other issues that block it, I don't like that it doesn't show up in the issue list, but it's not a big deal.

* I am also not sure whether the `size` category is redundant with the `effort` category.

* An issue with the label `effort/medium` or `effort/high` cannot really be a single task, from my point of view.

good first issue is also a somewhat redundant label, because it is basically effort/low.

Kinda, but there are issues that are low effort but absolutely not good first issues. Having "good first issue" as a separate label is meant to help new contributors, who don't really have any way to gauge what we mean by "effort/low".

Reducing the labels in the status category to:
* `meeting topic`

* `needs info`

* `needs vote`

* `needs review`

* `needs changes`

* `blocked`
would lead to missing issue states.

One example is needs review and in review. The first label provides a state in which it is clear that the issue needs a second person to review it, while the second signals that a person has already taken responsibility for the review and is actively working on it. Having both labels would make the KPI Review time possible and could, for example, lead to the conclusion that more reviewers are needed.

The problem is that absolutely nobody will ever remember to switch the labels, so it's meaningless and just takes up space in the label list.

Summary

Using Forgejo could be an interesting way to use labels not only for description, but also for data-driven decision-making. A well-thought-out balance between a minimal number of labels and label categories, and labels that can provide valuable insights into performance and improvement opportunities, could add real value to both the team and the users of the Docs.

We only want two very simple things from issue labels:

Before someone starts working on it: to tell people whether they should pick it up (indicate how big it is, and what the priority is, whether it's good for a new person)
After someone starts working on it: to indicate if it needs attention (needs vote/review/etc.)

We're not a company, we're "staffed" almost exclusively with volunteers who contribute in their spare time. KPIs are meaningless for us because I can't put someone on a PIP when their contributions drop too much compared to the previous quarter. So all having a ton of labels would do is annoy everyone. I also don't want issue states (beyond "needs doing/being done/finished" which is indicated without labels) because believe me, nobody would ever remember to switch the labels when they move an issue into another "state", so any data you might gather from these labels would be useless.

@a-moor wrote in https://forge.fedoraproject.org/docs/tickets/issues/40#issuecomment-713301: > ## [](#comments-to-pbokoc)Comments to @pbokoc > > `type/code` was meant to be used for specific customization of HTML, CSS, or JS. > > `type/infrastructure` was meant to be used for CI/CD and Forge-related topics. Yeah but 99% of our issues are `type/docs` and it doesn't make sense to distinguish between that and non-docs, so I'm just calling everything that isn't docs "infra". > `size/epic` is not a common word outside of agile workflows. Maybe `size/project` and `size/task` would be easier to understand for contributors without an agile project management background. Right, I think I'll just drop the whole `size` category. It's somewhat indicated by an issue having other issues that block it, I don't like that it doesn't show up in the issue list, but it's not a big deal. > * I am also not sure whether the `size` category is redundant with the `effort` category. > > * An issue with the label `effort/medium` or `effort/high` cannot really be a single task, from my point of view. > > > `good first issue` is also a somewhat redundant label, because it is basically `effort/low`. Kinda, but there are issues that are low effort but absolutely not good first issues. Having "good first issue" as a separate label is meant to help new contributors, who don't really have any way to gauge what we mean by "effort/low". > Reducing the labels in the `status` category to: > > * `meeting topic` > > * `needs info` > > * `needs vote` > > * `needs review` > > * `needs changes` > > * `blocked` > > > would lead to missing issue states. > > One example is `needs review` and `in review`. The first label provides a state in which it is clear that the issue needs a second person to review it, while the second signals that a person has already taken responsibility for the review and is actively working on it. Having both labels would make the KPI `Review time` possible and could, for example, lead to the conclusion that more reviewers are needed. The problem is that absolutely nobody will ever remember to switch the labels, so it's meaningless and just takes up space in the label list. > ## [](#summary)Summary > > Using Forgejo could be an interesting way to use labels not only for description, but also for data-driven decision-making. A well-thought-out balance between a minimal number of labels and label categories, and labels that can provide valuable insights into performance and improvement opportunities, could add real value to both the team and the users of the Docs. We only want two very simple things from issue labels: 1) Before someone starts working on it: to tell people whether they should pick it up (indicate how big it is, and what the priority is, whether it's good for a new person) 2) After someone starts working on it: to indicate if it needs attention (needs vote/review/etc.) We're not a company, we're "staffed" almost exclusively with volunteers who contribute in their spare time. KPIs are meaningless for us because I can't put someone on a PIP when their contributions drop too much compared to the previous quarter. So all having a ton of labels would do is annoy everyone. I also don't want issue states (beyond "needs doing/being done/finished" which is indicated without labels) because believe me, nobody would ever remember to switch the labels when they move an issue into another "state", so any data you might gather from these labels would be useless.

pbokoc commented

2026-05-29 09:41:18 +00:00

Author

Owner

Alright, so, I've settled on this setup:

type/content
type/misc

effort/high
effort/medium
effort/low

priority/high
priority/medium
priority/low

good first issue
help wanted
meeting topic
needs changes
needs reporter feedback
needs review

I dropped "blocked" because it overlaps with "needs X".

I also tried to give them some reasonable color coding (green/yellow/red for priorities and efforts, red for "needs X", etc.)

The labels are now available on all repos within the docs organization, you should be able to see them in any issue.

Alright, so, I've settled on this setup: type/content type/misc effort/high effort/medium effort/low priority/high priority/medium priority/low good first issue help wanted meeting topic needs changes needs reporter feedback needs review I dropped "blocked" because it overlaps with "needs X". I also tried to give them some reasonable color coding (green/yellow/red for priorities and efforts, red for "needs X", etc.) The labels are now available on all repos within the docs organization, you should be able to see them in any issue.

pbokoc closed this issue

2026-05-29 09:41:18 +00:00

Rows
Columns

[Repo alignment] Fix labels #40

Proposal: Issue Label Structure

1. Type

2. Effort

3. Priority

4. Status

Why this structure works

Why this is better than a mixed label set

Suggested workflow meaning

Closing note

Using Forgejo as a project management tool

Data- and KPI-driven decision-making and process optimization

Simplification vs. precision

Sub-goals, KPIs, and their calculations

Comments to @pbokoc

Summary

Comments to @pbokoc

Summary