Problem revealed: Discussion needed about Docs workflow organization

While working on the new workflow, we revealed issues in Implementing the new Docs workflow organization - Fedora Discussion

→ Merge Requests can be labeled and assigned, just like issues. But they cannot be added to the dashboard. This becomes an issue especially for external, or casual, contributors and their proposed MR.
→ some MR need follow-up commits or MR (if multiple branches are affected)
→ The triage has to be done in some way

In the above mentioned thread there is already some elaboration of the issue by me and @darknao

I agree with @darknao that it might cause unnecessary work to create a separated issue ticket for each MR, and that it can be questioned if this institution will survive on the long term. The current workflow would NOT include an issue ticket if an MR is directly processed by an assignee (including checking if it applies to multiple branches and then adjusting all affected branches at once). In other cases, it would include an issue ticket.

Additionally, there is the possibility of unprocessed MR (I think there were several in the past pagure repos), which indicates that we need to use the available time of members more efficient, and that we have to ensure an organization that does not forget these MR.

Also, it has to be ensured that MR are checked if they apply to multiple repos. E.g., many changes that are merged towards “main” should be also done in the current release branches (so F35 and F36 at the moment).

So, we have now three interrelated questions that might be discussed to then maybe find a consensus in the meeting:

  1. How to handle MR in the organization?

My proposal, which is a bit a compromise between my original approach and the suggestions of @darknao is:
→ expect from the members to check not only the dashboard but both the dashboard and the MR list once or twice per week. At the best, once before the weekly meeting.
→ we can use the same labels in the MR list. If you open the MR list, you can see immediately the labels of each MR. So you would see it if one is labeled “support needed” or “approval needed”.

As long as the number of MR is limited, this should work and is possibly more efficient than creating additional tickets.

If a member takes over an MR that merges into “main” and then does two additional commits to, e.g., F35 and F36 because it is a minor change that affects three branches, everything is fine anyway.

But if it is a major change that requires more than one MR, my suggestion remains to create an additional issue ticket because the ticket collects all related MR on its top (see an example here). This summary of related MR is initiated just by mentioning the ticket name in the MR or vice versa. This approach would also tackle the next question:

  1. How to ensure that each MR is checked for applicable branches?
    There are many proposed changes that require updates of multiple branches (e.g., main, F35, F36). The above approach is able to manage that, too.
    does it make sense to add an additional label here? Something like “multiple MR likely” or such. This could be added during the triage in conjunction with the major/minor label. A dedicated ticket makes here sense because the MR will disappear once it has been merged (creating the risk of forgetting about follow-up MRs/commits). However, that ticket could be created once it is for sure that multiple MR are necessary, not automatically in the beginning.

  2. How to do Triage? In meetings? Or asynchronously on the dashboard/MR list?

The workflow does not yet consider how we do triage. Indeed, my original idea was to become more independent of meetings: expect each member to check the dashboard (and the MR list), and if a member has some time to contribute, label what has to be labeled (if you know about the topic), and check what has already been labeled by someone else (so check what is already in the “triage” category to have a review of triage decisions). Then, if something needs approval or support, take over. If there is something already in triage which you could do, assign yourself.

My reason to suggest reducing dependency on meetings is:
→ the members lose time, in which they could contribute by processing an MR or so: e.g., the member is involved in 2 topics that are tackled in a meeting for 10 minutes, whereas the remaining 50 minutes tackle topics he/she is not involved in and thus, cannot contribute to (just an “extreme” example for illustration of my point).
→ the Docs lose time: besides the above, members have often to wait for the next meeting to find out if and where they can support/contribute (“unused contribution time” cannot be accumulated).
→ a meeting has to be scheduled: contributing for about 1 hour a week is easier than fixing in advance exactly when I have to contribute this 1 hour.
→ a triage would take much time if done in additional meetings, and the amount of time will increase with increasing contribution (much to schedule). It would take less time if the meetings are only to review the board/MR list and check what is going on and what remains unassigned but has to be done. The latter could be integrated into the weekly meeting.
→ more comprehensible documentation of activities, tasks, events.

The disadvantages of my approach, which would be mitigated by meetings:
→ my approach expects some “discipline” from members. It assumes that they regularly check the dashboard + MR list. We can see if the labeling gets done, but we cannot see if there is a well review of the labeling.
→ it should not be underestimated that it is not so easy to get used to such a new approach (labeling, document, etc.), and also to stay used to it → it has to prove competitive and to remain encouraged in the meetings and by the board.
→ the meetings are better in immediately responding to unforeseen developments/issues.
→ meetings might be better for team building
→ my approach feels very formal

Concerning new members:
Some potential new members might be encouraged by the boards where they can see in advance what they would be up against if they join the team (cognitive dissonance about what someone is up against can be very deterring), others would be encouraged by the meetings which enable them to participate without elaborating much in advance. I think this is balanced among the approaches and not really an argument for or against any of them.

Feel free to discuss. I have not yet added one of the approaches to the draft.

2 Likes

Your proposal in this thread makes sense to me.

I’m not sure we need to worry about that. In most cases when an edit is made to multiple branches, we can cherry-pick the appropriate commit. There’s no need to have people create a MR for the same change to each branch (I’d argue that it’s hostile to casual contributors).

Asynchronously is best. We can save meetings for discussion of particularly thorny MRs and to highlight ones that have sat for a long time (whatever we define that to be). We could maybe do a monthly meeting/hackfest to catch up on stagnant MRs.

2 Likes

Making cherry picks explicitly to the preferred way to transfer commits to other branches makes sense, I will put this in the draft. It was more the organizational part that made me worry. If there is only an MR without ticket, it will be closed and disappear in the list once merged. So everything has to be done at once or we would rely on a member to remember that something has to be done later.

But indeed, immediately creating a ticket is more or less the same than immediately do related cherry picks at once in terms of the time consumption: no real time saving. So I suggest to adjust the workflow to…

→ if there is a possibility that multiple branches are affected, add the label “multiple MR likely”,
→ if that label is added, identify in the discussion within the MR if multiple and which branches are affected and do NOT merge until all affected branches are identified.
→ if the result is that no other branches are affected, remove the label and proceed as usual.
→ if additional branches are identified, merging the MR and doing the related cherry picks has to be done at once. If already elaborated/approved in a discussion, a cherry pick is indeed just a few seconds.

No ticket, no reliance on a member’s memory, no risk of forgetting to transfer commits. And everyone can review/contribute to the issue (within the MR) at any time.

Also, I think if all is summed up in the Workflow page, it ain’t complicated because the labels are a good guide about what to do and how to proceed.

I will also explicitly note that there is a high tolerance for labels: if someone (e.g., a new member) is not sure if it is a only a minor, then make it a major: we can change it later anyway. The same for the “multiple MR likely” label: if unsure, add it. I think it makes sense for new members to know that there are no pressures here. Over time, they (and “we” in general) will develop coherent informal construing. Classifying some issues/MR initially too important (and later reducing the importance if it makes sense) avoids mistakes and is still likely to take less time than doing labeling in dedicated discussions in meetings.

I would even suggest to keep branches away from casual contributors whenever possible. When elaborating the 7-step HowTo, I found out that the branches were the major origin of confusion for people without git experience (that’s the reason why there are so many closed merge requests in the related issue ticket). Therefore, I formulated the 7-step HowTo to explicitly ignore branch-related aspects. So the 7-step HowTo assumes that one of the Docs members will take care of that later (we can change branches, etc. in the MR header in the GitLab-GUI with two clicks). So when someone uses this HowTo, it will be on us to identify which branches are affected. It just notes that contributors can comment if they already know in advance if multiple Fedora releases are affected, just as a general information.

So, I have written enough essays for today. If the adjusted approach is acceptable to all, I will adjust the draft in the next few days :slight_smile:

Suggestion:


The weekly meeting is to identify and tackle issues and tasks that are not ordinary or that do not occur regularly. The workflow management on the other hand is to manage the standardized daily operations of Fedora Docs.

However, the current issue tickets and Merge Requests of the workflow management can become regular topics on the weekly meeting: we have to regularly check if there are any unforeseen developments in the workflow that have to be discussed. Also, we have to identify and assign issue tickets and MR that remain unassigned for over two weeks, and discuss those that remain open one month after they have been assigned. Further, there can be thorny issue tickets and merge requests that need to be addressed and elaborated in a meeting before they can be completed.

To tackle these and other issues, the Fedora Docs team can decide to hold a monthly hackfest, if the weekly meeting proves to be not sufficient.

Does that make sense? And 2 weeks / one month for the review in the weekly meeting?


Full draft for the adjusted workflow is here (I’m still working on it, but feel already free to comment):
https://gitlab.com/py0xc31/documentation-contributors-guide/-/blob/adjusted-workflow/modules/contributing/pages/docs-workflow.adoc

I have not yet merged the adjustment into the existing merge request.

I think your suggestion makes sense.

Page not found.

I merged it to the existing MR so that we can discuss it today: