Skip to content

Changelog Workflows

Jump to bottom Edit New page
Tim Sutton edited this page Aug 28, 2020 · 20 revisions

Introduction

This workflow outlines the processing steps taken by changelog maintainers to ensure that pull requests providing new functionality (feature updates) are properly documented in order that they may be adapted and published in a format optimised for the user facing changelog that is published with each new release of QGIS. Here is an overview of the process:

QGIS-Changelog-Workflow

Diagrams.net source file for above image: (QGIS-Changelog-Workflow.zip) (scrub formward to around 3 minutes 30 seconds for the actual walk through to start).

Changelog walkthrough by Charles Dixon-Paver

General Workflow

  1. The changelog maintainer (currently GitHub user: zacharlie) is added to the ‘Community’ GitHub group which has triage rights

    image

  2. The changelog maintainer will read each Pull Request (PR) that has a Feature label as it comes in as per the following URL:

    https://github.com/qgis/QGIS/pulls?q=is%3Aopen+is%3Apr+label%3AFeature

    In the comments section, they will make a comment to the author if the feature is not clear / well described. We would be grateful if the PR gatekeepers could hold back on merging Feature PR’s that have issues, do not have a Changelog tag applied.

  3. Once the changelog maintainers are confident that the feature functionality is described well enough that a changelog entry of the expected quality standard may be produced, they will apply the Changelog label to the PR as per the following example.

    image

    After the Changelog tag has been added, the PR maintainers should feel free to merge the PR if they are happy with it.

Note that the English description doesn’t need to be perfect (it is understood that English may not be the mother tongue of many developers submitting features), however it is important that the functionality is well described. The English description will be edited for publication in step 6 below.

  1. Changelog tagged entries which have been merged will be harvested to the Changelog site regularly. This is done using the ingestion tool as shown in the screenshot below:

    image

  2. After closed Changelog PRs have been harvested, we will list the harvested entries on GitHub via the following URL:

    https://github.com/qgis/QGIS/pulls?q=is%3Apr+is%3Aclosed+label%3AChangelog

    First, the additional label on GitHub called ‘ChangelogHarvested’ will be applied to indicate that the entry has been harvested into the changelog content management site.

    Next, the Changelog label will be removed. This will prevent the same PR being reharvested (by the tool outlined in step 4) in subsequent harvest runs on the changelog platform, whilst retaining the relevant label required to indicate the PR contains a changelog entry.

  3. The entry will then be edited on the changelog site in order to get it ready publication, with the goal of having the content ready prior to the publication date for the new release. Additional volunteers from the changelog maintainers team will help improve the clarity and consistency of the entries on the changelog site. The entry should follow the conventions that are described in the "Conventions for changelog entries" section below. The goal here is to massage the description etc. to fit into our changelog entry form:

    image

  4. When the release comes near, the paid bug fixing entries added under 'Notable fixes' will need to be added. This is managed by Andreas Neumann.

    image

  5. After the changelog is finalised, changelog maintainers will notify Richard, who will then pull the changelog to the QGIS web site.

More on tagging

We will add the Changelog tag when a PR tagged with the feature label has been reviewed and the description has been considered descriptive enough (of the functionality) that a suitable changelog entry may be developed from the available material. Once a PR tagged Changelog is merged, it will be considered ready for ingestion and once harvested, the Changelog tag will be replaced with the ChangelogHarvested tag to prevent duplication on the changelog site.

We will basically have a number of states which are outlined as follows:

  1. Feature tag - PR description not reviewed or not suitable for inclusion in changelog
  2. Feature tag + Changelog tag: PR Not Merged - feature description suitable for inclusion in changelog
  3. Feature tag + Changelog tag: PR Merged - feature merged and ready for ingestion into changelog
  4. Feature tag + ChangelogHarvested tag + PR merged - entry has been ingested into changelog

Conventions for changelog entries

Once published, the changelog entries will be available at https://qgis.org/en/site/forusers/visualchangelogs.html

The entries will therefore need to comply with the associated stylesheets and conventions utilised with previous releases.

The following list outlines some basic guidelines for ensuring the entry content is of the required standards:

  • The feature title should be unique
  • Be categorised appropriately
  • Content should be articulate and concise
  • Not contain header tags such as <h1> as these will display on the changelog site as TOC links
  • Have a single thumbnail icon
  • Media should be explicitly added to the entry (downloaded to local and uploaded with changelog tool)
  • Language should generally be considered neutral, however developer comments or embellishments are permitted within reason

wiki footer here

Add a custom sidebar
Clone this wiki locally