La organización del Flujo de Documentos

Fedora Documentation Team Last review: 2023-04-24
Esta guía presenta miembros Docs y contribuidores aspirantes con el listado de etiquetas y categorías asociadas con Defectos y Unión de Solicitudes en el repositorio de GitLab Docs.

El equipo de Documentos de Fedora agradecen la organización del flujo de trabajo, la cual converge en las dos páginas centrales:

Pizarra GitLab

GitLab Abre Solicitudes de Unión

Tablero de emisión y etiquetas

Hay cuatro etiquetas que clasifican el estado de un ticket de problema.

  • Triage: Issue is labeled, 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”.

  • In progress: Someone has been assigned to this issue and it is in progress.

  • Support needed: Something was already done, but someone has to support the existing assignee or take over the assignment at all.

  • 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 afterwards.

"Open Merge Requests" do not contain a dashboard. 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.

  • 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.

  • 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).

  • Internal task: 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 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 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

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 without any labels.

  • Si se creó internamente, un miembro del equipo de documentación lo abrió. En el mejor de los casos, este miembro ya asigna una etiqueta de tipo y coloca los tickets de incidencia en la lista "Triaje", donde pueden esperar a que un asignado los tome. Lo mismo ocurre con las solicitudes de fusión, aunque no tienen listas de arrastrar y soltar y la etiqueta "Triaje" debe configurarse manualmente, al igual que la etiqueta de tipo. Como alternativa, el miembro creador puede asignar un asignado al ticket de incidencia/solicitud de fusión y luego colocarlo (arrastrando y soltando) en la lista "En curso" (esto implica agregar la etiqueta "En curso") en el panel, o agregar manualmente la etiqueta "En curso" si se trata de una solicitud de fusión.

En el panel, los ticket de incidencia se pueden mover por las listas arrastrando y soltando. Las etiquetas de estado cambian según corresponda. Si un ticket se mueve de "Triage" a "En progreso" arrastrando y soltando, la etiqueta de estado cambia de "Triage" a "En progreso". Por lo tanto, solo las etiquetas de tipo persistente deben configurarse manualmente una vez cuando el ticket es nuevo. Esto no aplica a las solicitudes de fusión en la página "Abrir solicitud de fusión". Al crear un ticket de incidencia en el panel, se le preguntará dónde crearlo. Si no está seguro de dónde crearlo, créelo en Fedora / Documentos de Fedora / Sitio web de documentos / Páginas de documentos de Fedora. Lo verá en la lista "Proyectos" ("Seleccionar un proyecto") que se muestra al hacer clic para crear un ticket de incidencia. Posteriormente, se mostrará como "fedora/docs/docs-website/pages".

El flujo de trabajo

Cambio menor

Si lo realizan miembros de Docs y se trata claramente de un "cambio menor", se puede realizar mediante una confirmación directa, sin necesidad de una solicitud de fusión ni un ticket de emisión. Si los miembros externos realizan una solicitud de fusión como "cambio menor", los miembros de Docs la fusionan inmediatamente tras asignarse a sí mismos y revisarla. Sin embargo, siempre verifique si un cambio aplica a varias ramas.

Si varias ramas se ven afectadas por un "Cambio menor", solo podrá fusionar/confirmar directamente si realiza la fusión/confirmación y la selección selectiva de todas las ramas afectadas a la vez. Si tiene dudas, añada la etiqueta "múltiples MR probables" a la etiqueta "Cambio menor" y mantenga la solicitud de fusión abierta para su discusión.

Dependiendo de la siguiente discusión, la etiqueta "múltiples MR probables" se eliminará si no hay otras ramas afectadas y entonces se podrá realizar la fusión o confirmación. Si hay otras ramas afectadas, se podrá realizar la fusión o confirmación y se seleccionarán todas las ramas afectadas de inmediato. El objetivo es que una solicitud de fusión no desaparezca de la página "Abrir solicitud de fusión" hasta que se complete la actualización de todas las ramas afectadas.

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:

  1. 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:

  2. 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.

  3. 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.

  4. 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).

  5. There are a few options.

    1. 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.

    2. 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).

    3. 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

"Multiple MR likely" can be transferred to "Major changes", which need an issue ticket or a Merge Request.

The workflow for a Major change is as follows:

  1. Determine the type and relabel Merge Request or issue ticket to Major change.

  2. Move new issues to the "Triage" list, or add the "Triage" label manually if it is a Merge Request.

  3. 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).

  4. There are a few options.

    1. The assignee finishes actively working* on the issue ticket/MR, and moves/puts it from the current state label to "Approval needed".

    2. 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.

Do not use the "stg" branch for content. Work in dedicated forks and branches for the specific issue you are working on.

Internal task

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

The weekly Docs meeting helps identify and tackle issues and tasks that are not ordinary or that do not occur regularly. On the other hand, the workflow organization is set to manage the standardized day-to-day operations of Fedora Docs.

The current issue tickets and Merge Requests of the workflow organization can become regular topics on the weekly meeting.

  • Check if there are any unforeseen developments in the workflow that needs a discussion.

  • 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 Docs meeting.

Want to help? Learn how to contribute to Fedora Docs ›