Skip to content

Added updating software components instructions

Andrew Patterson requested to merge docs-update-dependencies into master

What does this MR do?

Related issues

Closes #2347 (closed)

Design

  1. When upgrading a component, the author of the MR either creates or updates a test plan at a known location in the repository as part of the changes made to upgrade the component.
  2. The author and/or reviewers then execute this test plan as part of the development and review process.
  3. Check boxes in the test plan are updated to record progress on the test plan.

Test plan template

There is a test plan template/skeleton that can be used as a starting point when creating a new test plan. MR Authors copy this template into a new file and then edit it. An example can be found at sample test plan template.

Test plan location

The test plan can be located in either of two places doc/development or .gitlab/merge_request_templates. Either place has advantages and disadvantages over the other.

Test plans in doc/development

Test plans could located somewhere under doc/development (doc/engineering/test-plans/upgrade-<component>.md is proposed. In this case, the test plan is copied and pasted into the MR description by the author of the MR. It could also subsequently be copied and pasted into a comment for retesting by a reviewer.

Advantages
  • Easy copy and paste to a comment when you need to redo a test-plan.
  • Test plans will be checked by the docs-lint markdown job. This might also be a disadvantage as we may not want to run this job for something that is not really documentation. Perhaps we could put these files in a non doc/ directory, e.g,, <project-root>/test-plans.
Disadvantages
  • MR authors/reviews have to remember to copy in the test plan to the MR description.
  • Copy/paste of a possibly large file can be inconvenient.

Test plans in .gitlab/merge_request_templates

Test plans could be located in an MR template, one template per test plan (proposed .gitlab/merge_request_templates/upgrade-<component>.md).

Advantages
  • Test plan are automatically included in the MR description (as long as the author remembers to use the correct template). This saves a copy/paste operation in favor of a pull down menu item.
Disadvantages
  • There will be a lot of templates available in the template pull-down. The search function may help here and possibly sorting the test plan templates to sort last.
  • We can have over 100 of these test plans. If we put them in merge request templates, we will have a lot of common text that is not part of the test plan (required check boxs, for example). There is no "include" mechanism for GitLab Markdown, so if we modify something in these common elements, we will have to modify it in every one of the templates that include test plan which might be a maintenance nightmare. We could possibly write a pre-processor script that does an include operation to make this easier, but this would have to be run as part of the commit.
  • Copy and pasting test plans into comments will be slightly more difficult. You have to copy just the test portions of the MR template and their location is not as obvious.

Author's checklist

If you are only adding documentation, do not add any of the following labels:

  • ~"feature"
  • ~"frontend"
  • ~"backend"
  • ~"bug"
  • ~"database"

These labels cause the MR to be added to code verification QA issues.

Review checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review.
  • Ensure a release milestone is set.
Edited by Andrew Patterson

Merge request reports