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?