Internal Docs organization: GitLab workflow / process organization

We have started to tackle the organizational structure, but not the process organization.

I suggested GitLab originally to make use of its possibilities to organize workflows, but it remains a bit chaotic when I review the consolidated issues/dashboard of the repos. Therefore, I would like to start a discussion to create some process organization.

To start a discussion, I would like to put forward an approach to manage issues and Docs changes:

At the moment, when reviewing the consolidated Docs issues on the board, I cannot see what is waiting for someone to take responsibility, what is already in progress, what needs review/support, or who is responsible for what to at least know who to ask about it.

So I suggest to prepare the dashboard and organize issues/merge requests (MR) in a manner so that everyone can see at first glance what is going on and where contribution is necessary.

First, we already talked that minor changes in Docs do not need review when done by Docs members themselves so that it can be done by commit without MR (no issue ticket, no MR) (I think @bcotton or @pboy made that point sometime before). But if an external person makes a minor change, it ends up at a merge request. One of us has to approve that: because it is minor, the MR has to be labelled as minor so that the documentation contains information why no review was requested/done before the MR was merged by one of us. This is how we ensure that mistakes can become revealed (e.g., someone new has not yet fully understood the structures, and merges major changes without review).

So, when a major change is to be done, it should be created an issue ticket, and a MR, or vice versa if started by an external contributor. Both have to be labelled major. The issue ticket is to have it within our workflow/dashboard and to link different MR if the change has to be merged into multiple branches. Of course, the issue ticket and the MR have to be linked to each other.

Each issue ticket/MR needs an “assignee”! If more people are working on it, they can be added as “reviewers”. So as soon as someone is working on a ticket, take over the assignee role. If you finished the task but another one has to be conducted in this ticket/MR by someone else, remove yourself as assignee (and move the ticket on the dashboard accordingly, explained later in this post).

As soon as a major MR is ready, an approval has to be done by someone else! After that, it can be merged.

The “case study” with @computersavvy might be used as an example: he put forward an (assuming it is a major) MR (here), then I created a ticket (here) and linked both to each other. After making myself assignee and verifying the MR, I asked @darknao for a review. After doing the review, @darknao approved the MR, which you can see within the MR. Then, I merged. Because the change did also apply to other branches (f35, f36, main), further MR had to be done, which are all linked to each other through the issue ticket.

To have all organized on the dashboard, I suggest additionally to major/minor labels to add some workflow labels that become each a individual board on the dashboard, which the “major” tickets/MRs have to pass.

When opening the dashboard, I would like to see some boards while each ticket is moving from the left to the right. Beginning from the right:

  • open → ticket created, something has to be done, no one has yet taken over responsibility
  • in progress → someone has taken over responsibility and is assignee, he/she is working on it
  • support needed → someone has already done something here, but someone else has to take over responsibility (assignee removed) OR to support an existing assignee who keeps responsibility in order to finish the issue (content changes can but do not have to pass this board/label, but other issues beyond content changes may pass that!)
  • approval needed → this is a major change, someone has already taken over and IS STILL assignee, all is done, but someone has to do an approval before the assignee can merge
  • closed → closed.

So, a ticket can have multiple labels at once (e.g., major + approval needed), while we do not need dedicated boards for major and minor. Another label InternalTask without a dedicated board makes sense for internal tasks that are not content related. E.g., prepare something for the next meeting with labels “InternalTask” and “support needed” (it will appear with both labels on the “support needed” board).

An example for a dashboard like that can be found here.

Now the board shows at first glance what type of contribution is needed at which place. This also decreases the entry barrier for potential Docs members because they can see in advance what they are up against in terms of the organization, the tasks and the amount! This should not be underestimated.

A question that remains is if a minor that applies to multiple branches needs itself a ticket to link the commits (without MR), or if that condition makes it automatically to a major.

Another question that I discovered (here) is if another graphical HowTo for developers makes sense as well?

1 Like

Maybe the Issues feature is not enough for that?

What about using the Epics feature?

It seems to be a Premium feature, but we likely have access to it due to how Gitlab for Open Source works.

I think what you’re proposing makes sense as a starting point. We may need to tweak it as we use it.

I like the idea. In ‘support needed’ ticket, how about labelling ‘first time contributor’ for right-sized tasks so new (and enthusiastic) starters can jump in and achieve something. This will fuel more energy to contribute to heavy lifting down the line.

1 Like

Update from the meeting as of today:
→ first we will try without Epics, then let’s see how it works and maybe try Epics later.
→ as suggested by @darknao , add another category “triage” in between “open” and “in progress”: a new issue ticket can be already labelled and classified, so that we can see on the dashboard that, e.g., a “major” has to be assigned to someone → “triage” is already labelled/classified but has not yet an assignee.

1 Like

Well, externals that are not yet members (with GitLab “developer” rights) cannot assign a ticket to themselves. And we can only assign to those who are already in the group.

But the idea is indeed very interesting. I saw something like that already from the DEI team: but they put it into the discussion.fp → e.g., that: Help wanted: Contribute to Fedora D.E.I. Team documentation

Maybe we could start to do that as well? That may gather some interest. And I think more people look into discussion.fp. What do you think?

Contributors (everyone with an account) cannot assign themselves, but group members can assign them, they don’t need to be in the group.

+1 on this idea, maybe use good first issue as label name as it seems to be the default/standard on most git forge?

1 Like

I understand. It would be good to start self-assignment for members (currently 24 doc Group members). Let’s hear more feedback and discuss in the next days.

1 Like

When I go into one of our issues, I can only assign those people who are already member of the group. If I search another user name (both FAS and GitLab accounts), it will not be found (even if these user names have already opened MR in that repo). Is this maybe something only Owners can do?

No objection if this is possible. But doesn’t good first issue normally refer to issues these users have created themselves, to appreciate what they have put forward? I understood the idea of @hankuoffroad in the sense that we create this issue (which includes a task eligible for starters), and those who are interested, can then pick it to get to know Docs?

I think we should generally focus on self-assignment. This is why I thought a common dashboard makes sense. So everybody can see open tasks, and assign themselves if they have time and if the topic fits their experience. It would be no longer necessary to know in advance where to look at to identify what / if something has to be done. This fosters the self-organization. The additional category “triage” makes the dashboard even more comprehensible in its capability of presenting the members what has to be done/assigned. Then, someone who can spare some time does not need to wait for the next meeting or so to get assigned a task (just an example): instead, that member just has to check the dashboard & assign. The same if someone needs support.

Nevertheless, it might make sense that it is regularly checked if some unpopular tasks remain unassigned to put them explicitly forward in the meeting in order to identify an assignee. Maybe this can be a task that has to be allocated each week to one member, just like the chair of the meeting: the task may include to identify …
a) is an urgent task not yet assigned? and
b) is a task that is older than, e.g., 4 weeks still unassigned?

Isn’t the Fedora project on Ultimate tier yet that multi-level Epics comes as standard?

Solved by @darknao in the meeting: as soon as an external comments within an issue, the external can be assigned.

As agreed in the meeting, I will prepare the dashboard, labels, etc. according to

  • the original post
  • plus “triage” category+board
  • plus “good first issue” category+board