forked from docs/team-docs
Removed bold typeface when not necessary. Fixed wordiness.
This commit is contained in:
parent
8035cde7cb
commit
234959b965
1 changed files with 13 additions and 13 deletions
|
|
@ -1,6 +1,6 @@
|
|||
= The Docs Workflow organization
|
||||
Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
|
||||
:revdate: 2023-04-17
|
||||
:revdate: 2023-04-18
|
||||
|
||||
[abstract]
|
||||
This workflow organization is relevant for Docs members or people who want to become Docs members.
|
||||
|
|
@ -30,28 +30,28 @@ This is a major change and it needs an approval from someone else than the assig
|
|||
Additionally, there are three labels that classify the type of an issue ticket.
|
||||
|
||||
* Major change:
|
||||
This is a major change within Docs page(s). It needs a Merge Request and has to be approved by someone else than the assignee before it can be merged!
|
||||
This is a major change within Docs page(s). It needs a Merge Request 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 (a Merge Request is not mandatory)!
|
||||
This is only a minor change in Docs page(s). It does not need an approval, and it can be committed directly (a Merge Request 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/content! E.g., preparing a meeting or evaluating a survey.
|
||||
This is an internal task of Fedora Docs that is not a change, fix or update of a Docs page/content. (Example: preparing a meeting or evaluating a survey).
|
||||
|
||||
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! This is a good way to get in touch with Fedora Docs and the team, and to find out if you want to become yourself a member.
|
||||
|
||||
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): *multiple MR likely*. This label is added to ensure that all affected branches are identified and updated, and that Merge Requests that have this label are not merged without ensuring that the follow-ups are conducted and not forgotten (once accepted, a Merge Request disappears from the Open Merge Requests list, and remaining follow-ups are likely to become forgotten).
|
||||
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 ensuring that the follow-ups are conducted and not forgotten (once accepted, a Merge Request disappears from the Open Merge Requests list, and remaining follow-ups are likely to become forgotten).
|
||||
|
||||
Therefore, the "multiple MR likely" label ensures that all affected branches needs to be identified in advance to accepting any merge, whereas accepting the Merge Request and conducting the related cherry-picks have to be done at once. In short, you need to ensure that the Merge Request does not disappear from the Open Merge Request page until the update of all affected branches is ensured.
|
||||
Therefore, the *multiple MR likely* label ensures that all affected branches needs to be identified in advance to accepting any merge, whereas accepting the Merge Request and conducting the related cherry-picks have to be done at once. In short, you need to ensure that the Merge Request does not disappear from the Open Merge Request page until the update of all affected branches is ensured.
|
||||
|
||||
== How issue tickets and Merge Requests are created
|
||||
|
||||
There are two ways issue tickets and Merge Requests can be created: externally and internally.
|
||||
|
||||
* 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, also 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 (this implies adding the "Triage" label), 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.
|
||||
* 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".
|
||||
|
||||
|
|
@ -60,11 +60,11 @@ In some circumstances, it is possible to simplify the workflow of "Minor changes
|
|||
== 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 (including Minor changes) 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 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.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -80,8 +80,8 @@ The workflow for a *Minor change* is as follows:
|
|||
|
||||
. 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 (e.g., 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 himself/herself 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".
|
||||
.. 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".
|
||||
|
||||
=== "Major change" types
|
||||
|
||||
|
|
@ -91,7 +91,7 @@ The workflow for a change, which proves to be 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.
|
||||
|
||||
. 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. If you just want to do the "Triage", you are done now.
|
||||
|
||||
. 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).
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue