Changelog Workflows - qgis/QGIS GitHub Wiki

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 drawio

Diagrams.net source file for above image: (QGIS-Changelog-Workflow.zip).

Changelog walk through by Charles Dixon-Paver

Click the image above to play a YouTube video containing a walk-through by Charles Dixon-Paver (scrub forward to around 3 minutes 30 seconds for the actual walk-through to start). Note the diagram above was updated slightly and may differ from the one shown in the above video.

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 Changelog Candidate label as it comes in as per the following URL:

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

    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

    The ingestion tool harvest all closed PRs tagged with the changelog label. In some instances, PRs that may affect the changelog may not be merged, having been closed or considered stale. In such instances, the 'ChangelogExclude' label will be added so that these contributions will not be included in the harvesting process, but may be monitored and retagged with the 'Changelog' label in the future if the status of the pull request is changed.

  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. Prior to release, the Excluded Changelog entries that have not been harvested may be checked using the available GitHub filters to ensure that any previously excluded functionality that has been added is included in the changelog prior to release.

  5. Entries may be reviewed and edited from within the General section, but should only be assigned to a category once the content is publication-ready in order to easily segregate the records which have or have not undergone some form of review.

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

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

  • Changelog entries are created by migrating data from merged pull requests onto the changelog platform. This process will attempt to scrape the media and comments from the initial post. The original Pull Request is available from the entry editing page under the Github PR url field, and should be reviewed to ensure that all relevant media and commentary from the pull request is included in the changelog entry.
  • The feature title should be unique. Pull requests often use "tags" to automatically manage elements in the workflow such as adding the [Feature] label to the element title. All such elements should be removed, and the title should properly convey the new functionality introduced.
  • Each entry should be categorised appropriately. By default, all newly imported entries will be included in the "General" category, however only entries that truly belong in the general category should be categorised as general by the time of publication.
  • Content should be articulate and concise. Details from the pull request relating to developer specific content or items specifically for the documentation team can be removed. Some information on the feature utilisation is suitable, however it should not be verbose.
  • Git/ GitHub specific references such as 'This PR adds' introductions should be modified to 'Functionality was introduced to' or 'We have added'.
  • References to issues and pull requests, such as Fixes #123456 should ideally be modified to full descriptive links, e.g. This addresses the limitations identified in <a href="https://github.com/qgis/QGIS/issues/123456">issue 123456</a>.
  • Entry content should not contain any header tags such as <h1>, <h2> or <h4> etc. as these will display on the changelog site as links within the TOC (table of contents).
  • Each entry should have a single primary thumbnail icon. Additional media elements should be embedded in the content body.
  • Special characters should be avoided. Where relevant, move special characters like parenthesis and extraneous description elements from the entry title and into the description body.
  • Media should be explicitly added to the entry (downloaded to local and uploaded with the changelog tool).
  • Language should generally be considered neutral, however developer comments or embellishments are permitted within reason. American English is the preferred standard for spelling and grammar.
  • A historical context, or past tense, should be preferred when writing entries. Remember that PRs are written in the context of introducing neew functionality, whereas changelog entries are referring to features that have already been merged.
  • In some instances, especially with complex functionality, additional details or media on the feature may be discussed within the comments of the original PR on GitHub, which should be reviewed where relevant and included in the changelog entry.
  • References to oneself should be changed to group pronouns (i.e. 'I' becomes 'we')
  • Each developer tends to have different styles and standards for the structure and format of the entry content. Where possible, we should endeavour to keep things as consistent with the other entries as possible.
  • In some instances, a feature may be refactored from the original work of an author and merged by core maintainers. This is typically denoted by a Supersedes #1234 message. In these instances, changelog maintainers will need to try review the content from the original PR for changelog materials, and include some information that identifies the contributions of original authors.
  • Note that in many instances, additional context, media, updates, or additional information is available from the PR link and only the initial commentary is captured to the changelog platform, which can be enhanced with the material available from GitHub.
  • Merging entries may make sense in some instances where a large body of work has been segregated into multiple distinct PRs. The context for these entries is managed by reviewing the functionality history on GitHub.
  • Some PRs are also written in the context of awaiting a functionality that exists at the time of release. They may refer to various components or changelog entries that have a better frame of reference considering the current context. These references need to be removed or updated to ensure consistency.

Get involved

The QGIS developers have been increasingly adding loads of new functionality with each release, and as the number of new features increases, so does the effort required to maintain the changelog. Maintaining and contributing to the QGIS changelog is a great way for community members with strong command of the English language and decent writing ability to get involved with the project without the need for significant specific knowledge or other advanced skills. It's also a way for experienced members to perform a few quick and easy contributions when they have other time constraints.

First make sure you've signed up with an account at https://changelog.qgis.org

Then, in order to get "edit" access to changelog entries, you will need to get in touch with the changelog maintenance team. Simply send an email to charles[at]kartoza.com or tim[at]kartoza.com and express your interest.

Once you've been assigned the correct permissions, you will find the link to the latest release changelog at the bottom of the home page.

release list