Changelog

Changelog#

Estimated reading time: 6 minutes

The changelog is managed and orchestrated with towncrier.

The root level changelog directory contains ReStructuredText (.rst) news fragment files that each describe a change made to geovista. These news fragment files will be removed, combined and then added as the final release notes by towncrier to the root level CHANGELOG.rst file when performing a release of geovista.

The intended audience of the CHANGELOG.rst are users. Therefore, avoid describing low-level internal details only suitable for contributors, if possible.

When describing a change in its news fragment file make sure to use full sentences in the past or present tense with appropriate punctuation, for example:

Skip tests if their optional package dependencies are not installed.

or

Cross-referenced module headings to improve primary sidebar readability.

Don't use a leading tilde (~) for shortened cross-references to the API. Instead always use fully-qualified cross-references for audience clarity e.g.,

Cross-Reference

Rendered Output

:func:`geovista.transform.transform_points`

geovista.transform.transform_points()

:func:`~geovista.transform.transform_points`

transform_points()

The exception to this rule is when clear context is provided e.g.,

Updated :mod:`geovista.transform` such that :func:`~geovista.transform.transform_point`
and :func:`~geovista.transform.transform_points` optionally trap projection exceptions.

The following extlinks conveniences may be used within a news fragment file:

  • :issue: - Link to a geovista issue e.g., :issue:`123`

  • :pull: - Link to a geovista pull-request e.g., :pull:`456`

  • :user: - Link to a user e.g., :user:`bjlittle`

注釈

Remember to acknowledge the author/s of a pull-request with the :user: extlink. Some examples:

Added an awesome new feature. (:user:`bjlittle`)

:user:`ukmo-ccbunney` fixed a nasty bug. Closes :issue:`67`.

A breaking change co-authored by :user:`ukmo-ccbunney` and :user:`bjlittle`.

Each news fragment file must be named as <PULL-REQUEST>.<TYPE>.rst, where <PULL-REQUEST> is the pull-request number, and <TYPE> is one of:

  • breaking: Removals and backward incompatible breaking changes that may affect user code

  • deprecation: Declaration of removals and backward incompatible changes

  • feature: New user facing behaviours or capability

  • enhancement: Updates to existing behaviours or capability, including performance

  • bugfix: Correction to undesired behaviours or reported bugs

  • dependency: Package dependency removals, additions, pins etc

  • asset: Data, media and asset updates etc

  • documentation: Notable changes to the documentation structure, content, render or build

  • internal: Miscellaneous internal and maintenance changes

  • community: Celebrate our awesome community members and their contributions, including social changes

  • contributor: Changes that affect contributors such as standards, conventions, running tests, building docs, environments, security etc

  • misc: Catch all for items that don't fit elsewhere

e.g., 123.feature.rst or 456.bugfix.rst.

towncrier is configured in the pyproject.toml. For further details see the [tool.towncrier] section. Note that the order of the [[tool.towncrier.type]] entries is significant, as it is mirrored in the final rendered changelog.

If you're unsure what news fragment <TYPE> to use, then don't hesitate to ask in your pull-request.

Tip

If a change is associated with more than one pull-request, then create a news fragment file for each pull-request with identical content e.g., a change associated with 3 pull-requests has the following 3 news fragment files 101.feature.rst, 102.feature.rst and 103.feature.rst, all of which contain exactly the same content.

towncrier preserves multiple paragraphs and the formatting within a news fragment file, however concise single paragraph entries are encouraged.

Tip

Run towncrier --draft to render a preview of the news fragment files in the changelog directory.

Changelog Quality Assurance#

Quality assurance of changelog contributions is performed by the ci-changelog Action.

It performs the following automated checks on each pull-request:

  • Ensures that the pull-request includes a changelog news fragment

  • The news fragment file conforms with the expected <PULL-REQUEST>.<TYPE>.rst naming convention i.e.,

    • The <PULL-REQUEST> component is a valid integer and matches the pull-request number

    • The <TYPE> matches a configured [[tool.towncrier.type]] entry in the pyproject.toml

    • The rst extension is provided

  • The news fragment contains at least one author attribution e.g., :user:`bjlittle`.

These quality assurance checks can be skipped by adding the skip-changelog label to the pull-request. Note that a pull-request generated by the following bots or services will have the skip-changelog label automatically applied:

Also, see the ci-label Action for automated pull-request labelling.

Removing the skip-changelog label from a pull-request will trigger the ci-changelog Action workflow.

On this page