jonashub/team-docs
1
0
Fork 0
forked from docs/team-docs
Code Pull requests Activity

reworded for simplicity and readability

Browse source
This commit is contained in:
hank L 2023-04-19 13:52:05 +00:00
commit 0b6669eb1a
1 changed files with 27 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

56
modules/ROOT/pages/organizational/workflow.adoc
View file

@ -40,9 +40,9 @@ This is an internal task of Fedora Docs that is not a change, fix or update of a
Each issue ticket and each open Merge Request has to be labeled additionally with one of these three labels. The type labels do not change during the workflow.
Beyond a state label and a type label, issue tickets and merge requests can be additionally labeled as "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.
Beyond a state label and a type label, issue tickets and merge requests can be additionally labeled as "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 self-assign.
Furthermore, there is an additional label for Merge Requests that could possibly affect more than one branch, which would mean that they require follow-up Merge Requests or follow-up cherry-picks (the latter is preferred). The *multiple MR likely* label ensures that all affected branches are identified and updated, and that Merge Requests that have this label are not merged without the MR review.
Furthermore, there is an additional label for Merge Requests that could possibly affect more than one branch, which would mean that they require follow-up Merge Requests or cherry-picks. The *multiple MR likely* label ensures that all affected branches are identified and updated, and that Merge Requests are not merged without the MR review.
== How issue tickets and Merge Requests are created
@ -51,59 +51,57 @@ There are two ways issue tickets and Merge Requests can be created: externally a
* If created externally, they are created by people from outside the Fedora Docs team, who opened them in GitLab or using the "Report an issue" (creates issue tickets) / "Edit this page" (creates Merge Requests) buttons on any Fedora Docs page (the buttons are on the top right). Tickets will appear in the list "Open" on the dashboard without any labels. The Merge Requests will appear on the Open Merge Requests page without any labels.
* If created internally, one of the Docs Team opened it. At the best, this member already assigns a *type label* and puts issue tickets into the "Triage" list, where the ticket can wait for an assignee to take over. It is the same for Merge Requests, although they do not have drag & drop lists and the "Triage" label has to be set manually just like the type label. Alternatively, the creating member can already assign an assignee to the issue ticket / Merge Request and then put (drag & drop) an issue ticket on the "In progress" list (this implies adding the "In progress" label) on the dashboard, or manually add the "In progress" label if it is a Merge Request.
On the dashboard, issue tickets can be moved among the lists with drag and drop. The respective state labels are changed automatically. If a ticket is moved from "Triage" to "In progress" by drag and drop, the state label is changed automatically from "Triage" to "In progress". Therefore, only the persistent type labels have to be set manually once when the ticket is new! This does not apply to Merge Requests on the Open Merge Request page. When creating an issue ticket on the dashboard, you will be asked where to create the issue ticket. If you are unsure where to create an issue ticket, create it in Fedora / Fedora Docs / Docs Website / Fedora Docs pages. You will see this in the "Projects" list ("Select a project") which is shown when you click to create an issue ticket. Later, this will be shown as "fedora/docs/docs-website/pages".
On the dashboard, issue tickets can be moved along the lists with drag and drop. The state labels change acoordingly. If a ticket is moved from "Triage" to "In progress" by drag and drop, the state label is changed from "Triage" to "In progress". Therefore, only the persistent type labels have to be set manually once when the ticket is new. This does not apply to Merge Requests on the Open Merge Request page. When creating an issue ticket on the dashboard, you will be asked where to create the issue ticket. If you are unsure where to create an issue ticket, create it in Fedora / Fedora Docs / Docs Website / Fedora Docs pages. You will see this in the "Projects" list ("Select a project") which is shown when you click to create an issue ticket. Later, this will be shown as "fedora/docs/docs-website/pages".
In some circumstances, it is possible to simplify the workflow of "Minor changes" when it comes to creating or managing Merge Requests and issue tickets. See below.
== The workflow
=== Minor change
== The three workflows
=== "Minor change" types
If conducted by Docs members, and if it is clearly a "Minor change", a change can be done by a direct commit, without a Merge Request or issue ticket. If externals make a Merge Request as "Minor change", Docs members merge it immediately after they assigned themselves and reviewed the Merge Request. But always check if a change (including Minor changes) applies to multiple branches.
If conducted by Docs members, and if it is clearly a "Minor change", a change can be done by a direct commit, without a Merge Request or issue ticket. If externals make a Merge Request as "Minor change", Docs members merge it immediately after they assigned themselves and reviewed the Merge Request. But always check if a change applies to multiple branches.
If multiple branches are affected by a "Minor change", you are only allowed to directly merge/commit if you do the merge/commit and the cherry-picks to all affected branches at once. If you are unsure, add the "multiple MR likely" label additionally to the "Minor change" label and keep the Merge Request open for discussions.
Depending on the following discussion, the "multiple MR likely" label will be removed if there are no other affected branches and then the merge or commit can be conducted, or if other branches are affected, the merge or commit can be conducted and a cherry-pick to all affected branches will be done immediately and at once with the merge or commit. The goal to achieve here is that a Merge Request does not disappear from the Open Merge Request page until the update of all affected branches is ensured.
Depending on the following discussion, the "multiple MR likely" label will be removed if there are no other affected branches and then the merge or commit can be made, or if other branches are affected, the merge or commit can be conducted and a cherry-pick to all affected branches will be done immediately and at once with the merge or commit. The goal to achieve here is that a Merge Request does not disappear from the Open Merge Request page until the update of all affected branches is complete.
If the discussion takes place within an issue ticket (using commits instead of Merge Requests, or using multiple Merge Requests that are converged within a ticket) and not within one Merge Request, the commit and the cherry-picks can be done at different times: the issue can be kept open until all work is done, and has to be closed manually after that.
If the discussion takes place within an issue ticket (using commits instead of Merge Requests, or using multiple Merge Requests that are converged within a ticket) and not within one Merge Request, the commit and the cherry-picks can be done separately.
The workflow for a *Minor change* is as follows:
. If it is only a commit which clearly is a "Minor change", just do it. If you know in advance which branches are affected and if you can do the commit and all related cherry-picks immediately and at once, just do it. Then, you are done. If you have not sufficient time at the moment, and in all other cases, proceed as follows:
. If it is only a commit which clearly is a "Minor change", just do it. If you know what branches are affected and if you can do the commit and all related cherry-picks, go ahead. If you have not sufficient time to complete the task, proceed as follows:
. Determine the type and assign the related type label ("Minor change", "Major change", "Internal task". Here: Minor change) to the existing Merge Request or the existing issue ticket, or if non is existing yet: create one! If you are unsure what to create, create an issue ticket! Also, add "multiple MR likely" if there is a possibility that this is applicable.
. Determine the type and assign the related type label ("Minor change", "Major change", "Internal task". Here: Minor change) to the existing Merge Request or the existing issue ticket, or if non is existing yet: create one! If you are unsure what to create, create an issue ticket.
. Move new issues to the "Triage" list (which, as elaborated above, automatically assigns the "Triage" state label), or add the "Triage" label manually if it is a Merge Request. *If you just want to do the "Triage", you are done now!*
. Move new issues to the "Triage" list (which, as elaborated above, automatically assigns the "Triage" state label), or add the "Triage" label manually if it is a Merge Request.
. Now, the issue ticket or the Merge Request can be assigned to a member who takes over. Once someone has been assigned, the ticket has to be moved to "In progress" (change to "In progress" has to be done manually for Merge Requests).
. The issue ticket or the Merge Request can be assigned to a member who takes over. Once someone has been assigned, the ticket has to be moved to "In progress" (change to "In progress" has to be done manually for Merge Requests).
. Now there are three possibilities:
.. The assignee finishes the issue ticket/MR, and correspondingly, moves/puts it from the current state label to "Closed". If multiple branches are to be changed and if the case is handled within an MR, all branches have to be changed at once (as elaborated before). Type labels and additional labels shall remain.
.. Alternatively, the assignee needs support, or additional opinions: the ticket/MR is just moved to "Support needed" to identify supporter(s) (who can, but do not have to, be assigned as additional assignee(s) if that makes sense) and once sufficient supporter(s) have been identified, move/put it back to "In progress". Use "Support needed" to encourage a discussion in the ticket/MR and to get additional opinions. Once all work is finished, the ticket/MR can be moved/put to "Closed". If multiple branches are to be changed and if the case is handled within an MR, all branches have to be changed at once (as elaborated before). Type labels and additional labels shall remain. Members are free to change the responsible assignee (Example: if someone else has more experience with the next task, or can invest more time).
.. If the assignee has to give up the assignment at all, the assignee is free to decide what makes more sense in the given case: put it to "Support needed" and accompany the process of identifying a new assignee, or make a comment that sums up what was done and what remains to be done, remove the assignee and put it back to "Triage".
. There are a few options.
.. The assignee finishes the issue ticket/MR, and correspondingly, moves/puts it from the current state label to "Closed". If multiple branches are to be changed and if the case is handled within an MR, all branches need to be changed at once.
.. Alternatively, the assignee needs support, or additional opinions: the ticket/MR is just moved to "Support needed" to identify supporter(s) (who can, but do not have to, be assigned as additional assignee(s) if that makes sense) and once sufficient supporter(s) have been identified, move/put it back to "In progress". Use "Support needed" to encourage a discussion in the ticket/MR and to get additional opinions. Once all work is finished, the ticket/MR can be moved/put to "Closed". If multiple branches are to be changed and if the case is handled within an MR, all branches have to be changed at once. Members are free to reassign the issue (Example: if someone else has more experience with the task, or can invest more time).
.. If the assignee can no longer support the issue, the assignee either relabels the issue to "Support needed" and finds a new assignee, or makes a comment for the work completed and remaining work, removes the assignee and changes the state to "Triage".
=== "Major change" types
=== Major change
The handling of "multiple MR likely", as described for "Minor changes" above, can be transferred to "Major changes". However, "Major changes" always need an issue ticket or a Merge Request.
"Multiple MR likely" can be transferred to "Major changes", which need an issue ticket or a Merge Request.
The workflow for a change, which proves to be a Major change, is as follows:
The workflow for a Major change is as follows:
. Determine the type and assign the related type label ("Minor change", "Major change", "Internal task". Here: Major change) to the existing Merge Request or the existing issue ticket, or if non is existing yet: create one! If you are unsure what to create, create an issue ticket! Also, add "multiple MR likely" if there is a possibility that this is applicable.
. Determine the type and relabel Merge Request or issue ticket to *Major change*.
. Move new issues to the "Triage" list (which, as elaborated above, automatically assigns the "Triage" state label), or add the "Triage" label manually if it is a Merge Request. If you just want to do the "Triage", you are done now.
. Move new issues to the "Triage" list, or add the "Triage" label manually if it is a Merge Request.
. Now, the issue ticket or the Merge Request can be assigned to a member who takes over. Once someone has been assigned, the ticket has to be moved to "In progress" (change to "In progress" has to be done manually for Merge Requests).
. The issue ticket or the Merge Request can be reassigned to other members. Once someone has been assigned, the ticket moves to "In progress" (change to "In progress" done manually for Merge Requests).
. Now there are three possibilities:
. There are a few options.
.. The assignee finishes actively working* on the issue ticket/MR, and moves/puts it from the current state label to "Approval needed".
.. Alternatively, the assignee needs support, or additional opinions: the ticket/MR is just moved to "Support needed" to identify supporter(s) (who can, but do not have to, be assigned as additional assignee(s) if that makes sense) and once sufficient supporter(s) have been identified, move/put it back to "In progress". "Support needed" can also be used to encourage a discussion in the ticket/MR, to get additional opinions or incentives. Once actively working on the ticket/MR is finished, the ticket/MR can be moved/put to "Approval needed". Members are free to change the responsible assignee if someone else has more experience with the next task, or can invest more time.
.. Alternatively, the assignee needs support, or additional opinions. The ticket/MR moved to "Support needed" to identify supporter(s). Once sufficient supporter(s) volunteer, move the issue back to "In progress". "Support needed" can also be used to encourage a discussion in the ticket/MR, to get additional opinions. Once complete, the ticket/MR can be moved to "Approval needed". Change the responsible assignee to someone who has more experience with the next task, or can invest more time.
If multiple branches are affected, add the "multiple MR likely" label. If this label is assigned, the discussion within the ticket/MR has to identify all affected branches. In the end, the Merge Request has to be transferred to all affected branches through cherry-picks. If multiple branches have to be changed, all changes have to be done at once.
IMPORTANT: Do not use the "stg" branch for content. Work in dedicated forks and branches for the specific issue you are working on.
=== "Internal task" types
=== Internal task
Internal tasks are flexible. They might start in "Open" or "Triage", and move through "Triage", "In progress", "Support needed" until they can be "Closed".
Internal tasks are flexible. They start in "Open" or "Triage", and move through "Triage", "In progress", "Support needed" until "Closed".
== The role of the weekly meeting
@ -115,4 +113,4 @@ The current issue tickets and Merge Requests of the workflow organization can be
* 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.
* Use *Meeting* label for issues or MR to be discussed in the Docss meeting.
* Use *Meeting* label for issues or MR to be discussed in the Docs meeting.