Docs Squad processes

Documentation Squad Processes and Procedures

This page collects team processes and procedures for handling various situations.

For more information about any of them, ask the squad coordinator, or another team member.

1. Document History

2. Issue Handling

   • Spacewalk Repo

   • Uyuni-docs Repo

   • Bugzilla

3. Picking up Work

   • Backporting Changes

4. Branch Handling

5. Changelogs

6. Deprecating a File

7. Backlog Maintenantce (ex. Grooming the Backlog)

8. Meeting Attendance

9. Release Management

10. Snippets

11. Weekly Report

Document History

Author	Version	Date	Description
Joseph Cayouette	v1.2	2022-03-29	Moved document to sidebar
Ornela Maric	v1.1	2021-11-29	Reorganisation and tidying up of the file
Lana Brindley	v1.0	2020-09-22	Initial version

Issue Handling

We handle incoming requests for changes from several different sources. Ultimately, all work requests end up in the Docs project board in the spacewalk repository: https://github.com/SUSE/spacewalk/projects/31

Spacewalk Repo

Issues raised internally should be created in the spacewalk GitHub repository. In this repository, issues assigned to the Docs project board are automatically moved to the Backlog. When they are closed, they automatically move to column Done.

The squad coordinator grooms the backlog at least weekly, and assigns tags as appropriate:

• docs-squad - all issues that require attention from our squad

• documentation - issues that pertain to changes in the docs suite

• doc-process - issues that pertain to the docs toolchain

• Needs SME and Needs QA - use as required.

Uyuni-docs Repo

External users of the docs raise issues for us in the uyuni-docs GitHub repository. In this repository, you need to manually include issues on our squad board. Do this by creating a note in the backlog, and adding a link to the issue as the contents of the note.

When you add an issue from the uyuni-docs repo to our board, add the docs backlog tag to the issue. It is also a good idea to thank the contributor for the issue, to make it clear that someone on the squad has seen the issue, and it is going to be handled.

You need to manually progress these issues through the columns on the board, they are not automated.

❗	The doc-susemanager repository is deprecated, and must not be used for either issues or pull requests.

Bugzilla

When bugs are raised against the documentation, the RRBG creates a GitHub issue in the spacewalk repository and adds it to the docs project. From there, they are handled in the same way as other issues in the spacewalk repository.

Picking up Work

When you are looking for a new job to work on, start in the Backlog column on the Docs project board. This column is only minimally sorted. Prioritize work in this column in this order:

1. Issues above the waterline

2. Issues with an associated Bugzilla, especially with a higher service level number

3. Issues with a milestone recorded (sooner milestones first)

4. Issues with a release number label (sooner releases first)

5. Issues raised by external contributors

6. All other issues

When you have chosen a backlog item to work on:

1. Move the issue (or the note, in the case of issues in the uyuni-docs repo) to the Doing column.

2. Open the issue and make yourself the assignee.

3. Create a PR to address the issue. Ensure you include a link to the issue you are addressing in the PR description. Use Fixes if the PR fixes the issue completely (this closes the issue), or use Partial if you need to do more PRs.

4. When the PR merges, move the issue or note to the Done column.

5. Check that the issue and any related bugs are closed.

Branch Handling

The main branch for the documentation source code in the uyuni-docs GitHub repository is the master branch. By default, all changes to the documentation must be merged to master first, using a pull request. The content in master forms the basis of the next major product release, which usually happens annually.

To get content into an MU or a Beta release, you need to backport your changes to the appropriate feature branch. The next MU or Beta release is created from the feature branch.

The currently maintained feature branches are:

• 4.2: manager-4.2

• 4.1: manager-4.1

• 4.0: manager-4.0

Older versions of the documentation (3.2 and earlier) are no longer maintained.

For example, I want to get a fix into the 4.1.4 MU. I would create a PR to master with the fix and an appropriate changelog entry, and ensure I check the master and 4.1 checkboxes in my PR description..

When the PR to master is merged, I create a second PR to backport the changes to the manager-4.1 branch. This PR is merged before the 4.1.4 release process begins.

When packaging for the 4.1.4 release begins, the entire docs repo is frozen, and the manager-4.1 branch is used to create a new branch called manager-4.1-MU-4.1.4. The content in the new manager-4.1-MU-4.1.4 branch is built and published according to our usual build process.

Backporting Changes

If the changes in your pull request need to be published to a different version of the documentation, including beta versions or MUs, you must backport the changes to the appropriate feature branch.

Procedure: Backporting Changes to Feature Branches

1. Merge your PR to master by clicking Squash and Merge.

   

2. When the merge is complete, click the commit to see the full details and obtain the full commit number.

   

3. At the command prompt, checkout master and ensure your local copy is up to date:

   git checkout master
   git fetch --all
   git pull -ff

4. Checkout the feature branch you want to cherry-pick to, and ensure your local copy is up to date:

   git checkout manager-4.1
   git fetch --all
   git pull -ff

5. Create a new branch for the backport:

   git checkout -b backport41-edits-username

6. Cherry-pick the commit:

   git cherry-pick 6f59c822bf95296ed486c97a906b5ba7d0bb9e81

   If there are conflicts, go through each file, resolve the conflicts, and let this be a lesson to you to keep your PRs simple and touch as few files as possible to achieve your goal.

7. Push the changes:

   git add .
   git push

8. In the GitHub web interface, create the PR in the usual way. In the compare bar at the top of the Create PR dialog, select the appropriate feature branch as the base. This populates the PR with the details of the original change, and you should see the Able to merge notification.

   

9. Leave the PR title as it is populated, but prepend BACKPORT X.Y: to it.

   

10. Create the PR, and request reviews from the same people as reviewed and approved the original PR.

11. Make a note of the backport PR in the original PR, to make it easier to track.

    

Repeat this procedure for every feature branch that you need to put the original content into.

❗

Remember that master is considered the single source of truth for the documentation repository at any given point in time. If there are problems in a feature branch that are unrecoverable, they are rebuilt from master. Ensure you never merge anything to a feature branch that has not already been merged to master.

Changelogs

Changelogs are required when we package the documentation. To make it easier to keep track of the changes we have made to various versions of the documentation during the development period, we have a plain text .changelog file at the top level of the docs repository.

Not all changes you make require a changelog entry. Create a changelog entry if:

• The change is a relatively large change (such as a restructure, or if you have moved or renamed content).

• The change is related to a new feature in the product.

• The change is resolving a bug, and you have an associated bsc number (regardless of how large or small the change is).

Be concise in your changelog entries, but ensure they make sense to a reader. Additionally, strive for parallelism in the entries where possible, using the syntax <verbed> <noun> in <book name> (bsc#1234567). For example:

- Updated Foo chapter in Installation Guide for readability
- Documented Bar feature in Administration Guide
- Fixed error in Bat section of Upgrade Guide (bsc#1234567)

For official guidelines on writing changelogs, see https://en.opensuse.org/openSUSE:Creating_a_changes_file_(RPM)#Changelog_section_.28.25changelog.29

When you are reviewing PRs, remember to consider the changelog entry as well, for example:

• Does this change need a changelog?

• Does this entry make sense to a reader?

• Does this entry contain the correct bsc number?

• Does this entry use correct spelling and grammar?

• Could this entry be written more simply?

Always ensure your changelog entry is committed in the same PR as the change it relates to. This ensures that your changelog entry is backported to the correct feature branch along with the change, and is included correctly at packaging time.

Deprecating a File

The documentation is contained in a series of files, which loosely correspond to chapters within the books. In some cases, you might need to delete an entire file, either because a feature no longer exists, or because the content has moved into another location in the docs suite. In this case, we avoid deleting the file immediately, just in case we find out that some of the information is still useful, or we discover that the deletion was a mistake.

To remove a file from our docs suite, you first need to deprecate the file:

1. Leave the file in place in the directory structure.

2. Comment out the link to the file from the navigation page of the book, include the date of deprecation in your comment.

3. At the top of the file to be deprecated, add a comment explaining why the page is being deprecated, what page replaces it, and any other relevant info. Include your name and the date of deprecation in the comment.

This method ensures that the page is removed from the page structure on all publication endpoints, but does not remove it from search. This means that a suitable determined reader can still find the information.

When a file has remained in a deprecated state for at least twelve months, it is eligible for deletion.

Backlog Maintenantce (ex. Grooming the Backlog)

The squad coordinator grooms the backlog at least weekly. It should happen immediately before issuing the weekly report, and whenever otherwise required (for example, after returning from leave, or when there has been a lot of activity or new issues created).

To begin, ensure you have GitHub configured to watch the uyuni-docs, and doc-susemanager repositories. There is no need to watch the spacewalk repository, because you will just get overwhelmed with notifications. Relevant issues in that repository will come to your attention through the project board at https://github.com/SUSE/spacewalk/projects/31, or in meetings. Additionally, you might find it useful to watch the uyuni-project.github.io, doc-styleguide, and uyuni-docs-toolchain-vm repos, which are low traffic.

1. Check and clear your GitHub notifications. If you do this every morning, grooming will be much easier, and you will have much better situational awareness at any moment. I like to use the Chrome plugin Notifier for GitHub to help manage notifications.

2. Open the project board at https://github.com/SUSE/spacewalk/projects/31 and run your eyes down the Backlog column. Open anything that looks new to you and make sure you understand the context, refile or update labels as required. Anything in this column should have at least the docs-squad label, and to not be assigned to anyone in the docs squad. You can also re-sort this column by issue number, which can make it easier to keep track of things, especially if the backlog has more than 8-10 items in it.

3. Repeat for the Toolchain Backlog, ensure everything in this column has at least the docs-squad and doc-process labels.

4. Move things above the backlog waterlines if they:

   • Are related to an urgent, customer-facing bug

   • Have been reported by an external member of the Uyuni community

   • Is a release tracking issue

   • Is urgent for some other reason (for example, a last minute change before a release)

5. In the Doing column, re-sort the issues here by issue number, this will make writing the report simpler. Open every issue in the column, and check:

   • Does the issue have an assignee?

   • Is the assignee actively working on it (there should be a related PR)?

   • Are there any outstanding actions on the issue?

6. Open the related PR (or PRs) for each issue and check:

   • Is the assignee actively working on this PR (there should be recent commits)?

   • Is the PR properly formed (does it have a proper description, backports ticked, are the commits clean, is the changelog OK)?

   • Are there any outstanding comments or reviews on the PR?

   • Does the PR have backports required?

   • Can you review the PR?

   • Can you merge the PR (and do any backports)?

7. As a double check, go to https://github.com/uyuni-project/uyuni-docs/pulls and review every open PR in the same way as the previous step. You should have already seen most of these, but this way you’ll catch anything that isn’t associated with an issue on the board.

8. Check the Blocked column. This column doesn’t change much, so it can be easy to ignore, but try to keep on top of the issues in here, and move things along when you can.

9. Now is also a good time to check the release calendar, to check what’s coming up.

Remember that you can always view backlog stats here: http://grafana.mgr.suse.de/d/6YWZltSZz/overview?orgId=1

Meeting Attendance

All squad members are expected to participate in the daily squad standup (held on Mumble) on any day they are at work. This meeting is run by the squad coordinator, who will usually ping missing squad members five minutes before start. It is also usual practice for the squad coordinator to be in the meeting at least 5-10 minutes early for informal chat, and discussion of other topics as required. This also helps to break down the barriers of timezones, etc.

In addition to the standup, the squad coordinator is expected to attend:

Week 1:

• Review meeting (either live or on recording)

• Core team meeting

• Retrospective

Week 2:

• Docs Team meeting (note this meeting is held weekly, but could conflict with the core team meeting in Week 1)

• Priorities, Help & Planning (PHP)

Other team members are encouraged to attend meetings they find interesting, particularly the review meeting, retrospective, and the docs team meeting. However, it is the responsibility of the squad coordinator to attend meetings and ensure that any relevant information is passed on to team members.

Check https://github.com/SUSE/spacewalk/wiki/Meeting-timetable for the schedule.

Release Management

The squad coordinator is responsible for managing the various release preparation tasks, and ensuring that team members are aware of tasks related to upcoming releases.

For dates, use the release calendar (requires VPN): https://projects.nue.suse.com/calendar/month.php?cpath=&cal=SUSE-Manager

On the calendar, the 'branch freeze' dates are when we also need to have docs packages prepared. The release manager will ping you as the dates get closer to confirm the exact date that they want packages, but it’s important that you are ready before that happens. Note that Uyuni is released roughly once a month, but that Uyuni releases are not shown on the calendar.

About three days before packages are required, you need to freeze the docs repo:

1. Go to https://github.com/uyuni-project/uyuni-docs/pulls and open every pull request in a tab.

2. Look at each PR and determine if it needs to be merged before packaging. You should be able to determine this based on PHP and core team meetings, but ask the PO if you’re unsure about anything.

3. For PRs that do not need to be merged (or that will not be ready to be merged), edit the PR description, and add this as the top line:

   # ***DO NOT MERGE. DOCS REPO IS FROZEN***

   

4. For PRs that do need to be merged, keep them open for now, you will need to come back to them.

5. During the docs freeze, as new PRs are created, ensure you add the 'Do not merge' message during grooming.

6. Create the release checklist:

   • For a SUMA release, go to https://github.com/SUSE/spacewalk/issues, click New issue, and select the Documentation Release Checklist - SUMA.

   • For an Uyuni release, go to https://github.com/uyuni-project/uyuni-docs/issues, click New issue, and select the Documentation Release Checklist - Uyuni.

7. In the release checklist, in the Before Packaging Day section, list the PRs that you identified as being required for the release. If there are no PRs required, check the item, and add a note that you have confirmed there are no PRs to be merged. You can also begin work on the other items in this section.

8. In the Packaging Day section, ensure you update the release branch names to reflect the current release.

9. Make sure you have the correct labels applied to the checklist, and that they are reflected on the Project board. Keep them at the top of the Doing column so you can easily find them.

10. As a courtesy to the rest of the team, add an announcement to the Rocket Chat channel stating that the docs repo is currently frozen.

    

11. During the docs freeze, you need to keep a close eye on the release checklist, and ensure that things are being checked off as they are complete. The team should feel free to add notes and comments to each checklist item as they go, to help communicate the current status. This is especially important if you are not performing the packaging yourself, so that everyone knows what is happening.

12. When packaging is complete, and all items on the checklist have been completed, you can unfreeze the repo. You don’t always have to wait until the endpoints are live to unfreeze, but everything else should be complete.

13. Unfreeze the repo by removing the 'Do not merge' message from the open PRs, and merging anything that is ready. Also remember to remove the Rocket Chat announcement.

14. When the endpoints are live and have been checked, close the release checklist issue and move to the Done column.

Snippets

Snippets are short pieces of text that can be reused in various places in our documentation. These are useful in situations where we need to repeat the same content in multiple places, because we only need to maintain the content in a single location. These are used most frequently in the Client Configuration Guide, where the same procedures are used for various client OSs, with different parameters. In this case, the parameters are given in a table immediately above the snippet.

Things to consider before you create a new snippet:

• Will this snippet realistically be used in more than one place?

• Is the snippet sufficiently generic that it can be used in more than place, but not so generic that it is not useful to readers?

• Can I easily differentiate this snippet from others by name/title alone?

In most cases, writing the content directly in the file is preferred. There are limited genuine use cases for snippets in our current information architecture.

Weekly Report

The squad coordinator is responsible for writing the weekly report. This should be done either every Friday afternoon, or every Monday morning, and is sent to [email protected].

Remember that the report covers the calendar week that immediately precedes it, so ensure you use the correct week number in your subject line.

Now is also a good time to check the release calendar, to check what’s coming up.

❗	Ensure you have cleared your GitHub notifications and groomed the backlog before you begin writing!

Use this format:

To: [email protected]
From: Docs Squad coordinator
Subject: [WORK REPORT] Docs Squad - Week $x

-Highlights-

* Use dot points here to call out the main achievements of the previous week.
* These should be things that have been completed.
* Avoid 'in progress' updates, unless they took up a lot of time, or are particularly important.
* Taking notes during standup will help with populating this.

-Note-
Optional: use this for noting upcoming vacation or events (such as Hack Week or conference attendance).
If the docs repo is frozen, mention that here.


-In Progress-

[GREEN]
#xxx (uyuni-docs) - Description (Assignee)
#xxx - Description (Assignee)

This comes directly from the Doing column in https://github.com/SUSE/spacewalk/projects/31
Present it in issue number order.
Anything that is going to be delivered late, mark as [AMBER] or [RED] as appropriate.


[BLOCKED]
#xxx - Topic - Blocked by
#xxx - Topic - Blocked by


-Next-
* Use dot points here for the next most important things the squad is working on.
* Populate this with what's above the waterline in the backlog (don't include the whole backlog though).
* Include things like finalising existing work, release retros, end-to-end reviews, etc.