Implementing the new Docs workflow organization

I just prepared GitLab for the new organization, we discussed in Internal Docs organization: GitLab workflow / process organization and agreed in Docs meeting agenda: 2022-08-03

The dashboard is ready and I already did the “triage” for several issue tickets (feel free to challenge my classifications):

Also, I added my two “not major/minor related” tasks to “In progress” with the “Internal task” label, as an example.

I have created descriptions for all lists! If you keep your cursor on the list title, you will see a description that aims to explain what this is and what to do here (or what to do next). Maybe this helps a bit.

So it looks like that:

The descriptions are as follows:

  • Triage
    Issue is labelled & classified, but no one has been assigned yet. Do you want to take over? Feel free to assign yourself and shift the issue to “In progress”!

  • Good first issue
    You want to contribute to Fedora Docs? This is your opportunity! Feel free to comment in one of these issues that you want to take over!

  • In progress
    Someone has been assigned to this issue and it is in progress!

  • Support needed
    Something was already done, but someone has to support the existing assignee OR take over the assignment at all (see comments within the issue)!

  • Approval needed
    This is a major change and it needs an approval from someone else than the assignee! Feel free to take over the approval so that the assignee can merge after that!

The following labels do not have a dedicated list, but are additional to classify the issue ticket:

  • Major change
    This is a major change within Docs page(s). It needs a MR and has to be approved by someone else than the assignee before it can be merged!

  • Minor change
    This is only a minor change in Docs page(s). It does not need an approval, and it can be committed directly (an MR is not mandatory)!

  • Internal task:
    This is an internal task of Fedora Docs: every task that is not a change/fix/update of a Docs page! E.g., preparing a meeting or evaluating a survey.

Notes & issues:

  • When doing the triage, I considered a request for a new Docs page as “major change”. I don’t think we need another label for that, agreed?
  • As you know, any issue needs to be assigned to a project: I put the “Internal task” issue tickets to:
    Fedora → Fedora Docs → Docs Website → Fedora Docs pages
    Does that make sense?

@darknao forgive me my crimes in issue #6 :slight_smile:


I just identified one issue:

When externals create an MR, we have to manually create an issue ticket so that this MR ends up on the dashboard. Currently, no one seems to be responsible for external MR by default; there are already some: Merge requests · Fedora Docs · GitLab → are the external MR in that list already being processed by someone?

If we keep fostering external contributions (7-step HowTo and such), we have to consider that. We can assign labels to the MR, but MR will not be shown on the dashboard; only their issue tickets. (@darknao do you know any workaround for that?)

In short: We need not just to do the “triage” on the “open” tickets, but also on the “MR” list, whereas the latter also requires us to create an issue ticket.

If that makes sense, I have no problem with taking this responsibility for now (so, create a ticket for each external MR so that we have it on the dashboard). This task might be merged with doing Triage in general?

Workflow draft for the Team Docs page:

I just started to draft something, but feel free to already comment about it.

1 Like

Do we really need to do that? I understand you want to see them on the board, but for what purpose?
MR should be about done work. Either someone just wanted to fix a typo or other minor changes, and in that case, it’s only a matter of approval to get it merged.
Or it’s about a more complicated change and may require some further discussion. It can be in the MR itself, in a meeting, over here, or in a dedicated issue.
That should be per MR basis only, and most of the time, I don’t think we really need it.

Yes! We need to triage both new tickets and review MR. And I think the best way to do that is in a dedicated meeting. That should not be the responsibility of a single person to take that role.
This can be a short meeting, like 30 minutes top, where we review new issues and take a first look at new MRs.
Pretty much what we did some times ago, but in a separate meeting instead of the weekly one.

As a new contributor, there is nothing more discouraging than seeing a MR sitting there for 3+ months with no feedback. We don’t need to merge them right away, but at least a +1 or any kind of feedback/comment is always a good start.

This should be a label, IMO, not a column on the board. Columns should be states, not attributes. After all, moving to In progress or Support needed doesn’t mean it’s not still a good first issue.

This looks pretty good overall, but I suggest removing "The workflows of the three types: " which you repeat three time and have “Workflows” as an h2 with each type as an h3 under that.

Absolutely. I will change that.

Unfortunately, I do not understand that comment :slight_smile: What do you mean?

I thought it is the list where externals can pick tickets, and once a ticket has been assigned, the job of the label is fulfilled. But for me, both makes sense. I will delete the list and adjust the workflow page. So we keep such tickets in the “triage” with the additional label “good first issue”?

My argument was already based upon the workflow. So a ticket would be necessary only if it is a major change, or if a minor change MR requires additional MR (e.g., when different branches are affected) while the assignee does not want to do all these MR himself and at once. Especially for the latter, a ticket would not just enable asynchronous workflows (not bound to discussing in meetings) but also division of work.

I assume you mean that we should do the triage jointly in meetings, and also the allocation of MR. And the latter without tickets. Generally, we can do that and see how it develops.

But I see several issues with that, which already contributed to my decision to propose a workflow:

  1. We should not take it for granted that people can always dedicate time. We already struggled to fulfill tasks in the past. Sometimes, people can dedicate time, but they do not know if and where they can support (I had that already several times): waiting for the next meeting is not efficient. And then, there will be maybe too much to discuss in the meeting, so that much cannot be tackled.

  2. The meetings are already often overbooked. Often we have to shift topics to the next weeks, which increases the 1) issue. If we add weekly a discussion about determining what is major, what is minor change, what does maybe require additional MR in other branches, then we have two hour meetings, if not more when we achieve our goal of more external contributions. This also relates to the next issue:

  3. Currently, external MR seem to be approved/merged arbitrarily. What is done? By whom? Is there a check if a change affects other branches? If something is only merged into “main” but also affects the currently supported releases (which is often the case), it might take up to one year until all supported release branches contain this change. I agree that a minor change should be just merged, and if the self-assigning member of us has the time, it is the same if a minor affects several branches: make all at once, and then it is done without any tickets. But as soon as the job cannot be done in the very moment (or if a member does not want to do all himself/herself), I thought a ticket is a good thing to ensure that a) a check is done to ensure that all affected branches get adjusted and b) no one needs to do the whole job alone while c) it does not take much time in the meetings. So the idea was instead of meetings, everyone just has a look on the dashboard once or twice a week, and then contributes to what he sees/knows/has experience with, which may also lead to cross-checks.

A slight addition about meetings: what did annoy me once in the past was a meeting, where I joined for a 2 or 3 minutes topic, while I had no experience with the remaining topics we discussed, so I couldn’t contribute much. The outcome is that I lost much time that I could have used to contribute somewhere else.

So, I think the question that we have now is: what to do with external MR if they are major, if they are minor, and if they are minor with several branches affected (and how to ensure that the latter question is tackled and it’s follow-up MRs don’t become forgotten). And of course how/where to do this triage. I will wait a bit before I make further changes so that we can discuss that.

Is this realistic? Especially if we achieve the goal of more contributions, and then also discussing triages for each ticket/MR?

Absolutely agreed. This is why I suggested to ensure that they don’t get lost, that division of work gets enabled, and that we can persistently keep working without waiting for meetings. But in either case, we have to check and ensure that all affected branches get adjusted: can we ensure that if everything keeps consolidated in the one original MR? This makes us again dependent on having a meeting for that, and that we always check each single MR which and where we have to discuss. An issue always contains automatically a list of all related MR on its top (just like that one).

However, I will think myself a bit about the issue, alternatives, etc. as now that I identified it, I am not satisfied by my own solutions either.

An alternative would be to encourage members to not only check the dashboard but also the MR requests. And label them just like the tickets. If an MR needs support or requires additional MR, a ticket can be created as soon as this occurs (even if not on the dashboard list, an MR can still be assigned the “approval needed” label). This would work as long as there will be not too much external MR. Also, it would avoid that we waste time for creating additional tickets where they are not necessary.

The “good first issue” list on the dashboard is deleted. Plus:

1 Like

I’m referring to heading levels (h2 and h3 are the HTML elements). So the adoc file would be something like:

== Workflows

=== Minor changes

blah blah blah

=== Major changes

and so on

Is that more clear?

Yes, that makes sense. I’ll adjust it.

Edit: done

To keep this thread focused on the Docs page, I created another one for the issues that seem to be not yet covered by my original proposal:

I know it’s much stuff, but the better it becomes organized in the beginning, the more time we can save later (and the less unforeseen issues will occur).