standard template applied and style guide check - commit 1

modules/ROOT/pages/organizational/workflow.adoc

@@ -1,4 +1,9 @@
 = The Docs Workflow organization
+Fedora Documentation Team <https://discussion.fedoraproject.org/tag/docs>
+:revdate: 2023-04-16
+
+[abstract]
+This workflow organization is relevant for Docs members or people who want to become Docs members.
 
 The Fedora Docs team agreed on a workflow organization, which converges at the two central pages:
 
@@ -6,11 +11,10 @@ The Fedora Docs team agreed on a workflow organization, which converges at the t
 
 . https://gitlab.com/groups/fedora/docs/-/merge_requests[the GitLab Open Merge Requests]
 
-NOTE: This workflow organization is relevant for Docs members or people who want to become Docs members. Casual contributors, who just want to contribute to Docs content from time to time, should read the 7-step HowTo.
 
 == The dashboard lists and labels
 
-There are *four labels that classify the state of an issue ticket*:
+There are four labels that classify the state of an issue ticket.
 
 * Triage: 
 Issue is labeled & classified, but no one has been assigned yet. Do you want to take over? Feel free to assign yourself and shift the issue to “In progress”!
@@ -21,11 +25,11 @@ Something was already done, but someone has to support the existing assignee OR
 * Approval needed: 
 This is a major change and it needs an approval from someone else than the assignee! Feel free to take over the approval so that the assignee can merge after that!
 
-The *dashboard contains a list for each of these four labels*, additionally to the default "open" and "closed" lists of the GitLab dashboard. Usually, an issue ticket moves from the dashboard lists on the left to the right lists, although an issue ticket does not necessarily pass any list, and it is also possible that it moves back to the previous state (e.g., from "Support needed" back to "In progress" is a realistic development). So, the *state label* changes during the progress of an issue ticket.
+The dashboard contains a list for each of these four labels, additionally to the default "open" and "closed" lists of the GitLab dashboard. Usually, an issue ticket moves from the dashboard lists on the left to the right lists, although an issue ticket does not necessarily pass any list, and it is also possible that it moves back to the previous state (e.g., from "Support needed" back to "In progress" is a realistic development). So, the *state label* changes during the progress of an issue ticket.
 
 Unfortunately, the "Open Merge Requests" do not contain a dashboard, but they use the same labels in the same way! You can see all assigned labels of an open Merge Request at first glance when opening the "Open Merge Requests" page.
 
-Additionally, there are *three labels that classify the type of an issue ticket*:
+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!
@@ -51,9 +55,7 @@ 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, 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. 
 
-TIP: On the dashboard, issue tickets can be moved among the lists with drag and drop. The respective *state labels are changed automatically*. E.g., 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.
-
-TIP: 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 possibility 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 among the lists with drag and drop. The respective *state labels are changed automatically*. E.g., 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 possibility 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".
 
 NOTE: In some circumstances, it is possible to simplify the workflow of "Minor changes" when it comes to creating/managing Merge Requests and issue tickets. See below. 
 
@@ -66,9 +68,7 @@ If multiple branches are affected by a "Minor change", you are only allowed to d
 
 Depending on the following discussion, the "multiple MR likely" label will be removed if there are no other affected branches and then the merge/commit can be conducted, or if other branches are affected, the merge/commit can be conducted and a cherry-pick to all affected branches will be done *immediately and at once* with the merge/commit. The *goal* that has to be achieved here is: it has to be ensured that a Merge Request does *not disappear from the Open Merge Request page* until the update of *all* affected branches is ensured (once accepted, a Merge Request disappears from the Open Merge Requests list, and the follow-ups are likely to become forgotten). 
 
-Obviously, if the discussion takes place within an issue ticket (using commits instead of Merge Requests, or using multiple Mege 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.
-
-TIP: Because of facts provided in the two above paragraphs, it can make sense to converge changes, which could affect multiple branches, in an issue ticket and not in a Merge Request: this makes it possible to split different branches' merges/commits so that different branches have not to be changed at once. This can be decided by the responsible Docs member based upon the situation.
+Obviously, if the discussion takes place within an issue ticket (using commits instead of Merge Requests, or using multiple Mege 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. Because of facts provided in the two above paragraphs, it can make sense to converge changes, which could affect multiple branches, in an issue ticket and not in a Merge Request: this makes it possible to split different branches' merges/commits so that different branches have not to be changed at once. This can be decided by the responsible Docs member based upon the situation.
 
 NOTE: Despite the tip above, casual contributors are told in the 7-step HowTo to generally use the Merge Request if they want to propose a change and to ignore everything that has to do with branches: this aims to keep it short and simple for them. Nevertheless, they are of course free to create an issue ticket instead of Merge Requests.
 
@@ -128,11 +128,11 @@ Discussions shall take place within the respective issue ticket or Merge Request
 
 If somewhere in the workflow the labeling proves to be mistaken, it is changed correspondingly, and so the following workflow.
 
-TIP: Even if approved within an issue ticket, be careful with using commits for "Major changes". An additional MR makes it possible that the exact commit(s) can be reviewed by other members before merging because approval within an issue ticket does not avoid mistakes that occur in the commit. Therefore, an additional approval within an MR can make sense for bigger changes.
+Even if approved within an issue ticket, be careful with using commits for "Major changes". An additional MR makes it possible that the exact commit(s) can be reviewed by other members before merging because approval within an issue ticket does not avoid mistakes that occur in the commit. Therefore, an additional approval within an MR can make sense for bigger changes.
 
-IMPORTANT: The "stg" branch shall *not* be used for content/texts. You should work in dedicated forks/branches, which are just for the one issue you are working on, or commit directly to "main" if that is appropriate in the given case: in any case, the outcome of efforts should go directly to the "main" branch *without* "stg" in between.
+IMPORTANT: The "stg" branch shall not be used for content/texts. You should work in dedicated forks/branches, which are just for the one issue you are working on, or commit directly to "main" if that is appropriate in the given case: in any case, the outcome of efforts should go directly to the "main" branch *without* "stg" in between.
 
-TIP: Do not forget to rebase/update your fork/branch *regularly* in cases where contributions are not done by direct commits to "main". Do not wait too long before merging in order to avoid conflicts, which might force you to rebase conflicted changes manually (if conflicts appear, automated rebase will no longer work and it has to be done manually, which *cannot* be done within the GitLab IDE). Content/texts have no agency and thus, no dependencies: you can exploit this and split your work in flexible smaller pieces and commit/merge quickly one by one instead of working in long-standing huge MR. If direct commit is not sufficient, create a *dedicated fork* or a *dedicated branch* for your work, write the content, test it if necessary (e.g., using build.sh+preview.sh), merge, and then do the next piece of work. In short: keep forks and separated branches as close as possible to the downstream "main"!
+TIP: Do not forget to rebase/update your fork/branch regularly in cases where contributions are not done by direct commits to "main". Do not wait too long before merging in order to avoid conflicts, which might force you to rebase conflicted changes manually (if conflicts appear, automated rebase will no longer work and it has to be done manually, which *cannot* be done within the GitLab IDE). Content/texts have no agency and thus, no dependencies: you can exploit this and split your work in flexible smaller pieces and commit/merge quickly one by one instead of working in long-standing huge MR. If direct commit is not sufficient, create a *dedicated fork* or a *dedicated branch* for your work, write the content, test it if necessary (e.g., using build.sh+preview.sh), merge, and then do the next piece of work. In short: keep forks and separated branches as close as possible to the downstream "main"!
 
 === "Internal task" types 
 
@@ -148,8 +148,6 @@ Theoretically, the assignee should be always assigned to the Merge Requests just
 
 The weekly meeting is to identify and tackle issues and tasks that are not ordinary or that do not occur regularly. The workflow organization 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 organization 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: there is an *additional label "meeting"*, which can be assigned to issues/MR that need to be discussed in the next meeting. 
-
-NOTE: The label "meeting" can be assigned by any member. As with the other labels, it is better to assign it once too often than too few.
+However, the current issue tickets and Merge Requests of the workflow organization 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: there is an *additional label "meeting"*, which can be assigned to issues/MR that need to be discussed in the next meeting. The label "meeting" can be assigned by any member. As with the other labels, it is better to assign it once too often than too few.
 
 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.