Changelog.jl

Changelog.jl is a Julia package for managing changelogs.

Installation

Install using Julias package manager:

pkg> add Changelog

Documentation

The core idea of this package is to make it convenient to write changelog entries with references to pull requests/issues and let Changelog.jl generate the full URLs.

The typical workflow is as follows:

1. Write a changelog entry in the changelog file (e.g. CHANGELOG.md):

   - Description of new feature with reference to pull request ([#123]).
   

2. Run the command

   Changelog.generate(
       Changelog.CommonMark(),          # output type
       "CHANGELOG.md";                  # input and output file
       repo = "JuliaDocs/Changelog.jl", # default repository for links
   )

   This scans the input for link tokens, generates the full URLs, and inserts a link list at the bottom. A tip is to add the command above as a Makefile target. The output would be

   - Description of new feature with reference to pull request ([#123]).
   
   <!-- Links generated by Changelog.jl -->
   [#123]: https://github.com/JuliaDocs/Changelog.jl/issues/123
   

3. Commit the result.
4. Run the following command to integrate the changelog into documentation built with Documenter:

   # In docs/make.jl, before makedocs(...)
   Changelog.generate(
       Changelog.Documenter(),                 # output type
       joinpath(@__DIR__, "../CHANGELOG.md"),  # input file
       joinpath(@__DIR__, "src/CHANGELOG.md"); # output file
       repo = "JuliaDocs/Changelog.jl",        # default repository for links
   )

   The output in would be

   - Description of new feature with reference to pull request
     ([#123](https://github.com/JuliaDocs/Changelog.jl/issues/123)).
   

Parsing changelogs

Changelog also provides functionality for parsing changelogs into a simple structure which can be programmatically queried, e.g. to check what the changes are for a particular version. This functionality is primarily intended for parsing KeepAChangeLog-style changelogs, that have a title as a H1 (e.g. #) markdown header, followed by a list of versions with H2-level headers (##) formatted like [1.1.0] - 2019-02-15 with or without a link on the version number, followed by a bulleted list of changes, potentially in subsections, each with H3 header. For such changelogs, parsing should be stable. We may also attempt to parse a wider variety of headers, for which the extent that we can parse may change in non-breaking releases (typically improving the parsing, but potentially regressing in some cases).

The API for this functionality consists of:

• SimpleChangelog: structure that contains a simple representation of a changelog.
• VersionInfo: structure that contains a simple representation of a version in a changelog.
• Base.parse(SimpleChangelog, str): parse a markdown-formatted string into a SimpleChangelog and likewise Base.tryparse
• Changelog.parsefile (and Changelog.tryparsefile): parses a markdown-formatted file into a SimpleChangelog

For example, using Changelog.parsefile on the CHANGELOG.md as of version 1.1 gives:

julia> changelog = Changelog.parsefile("CHANGELOG.md")
SimpleChangelog with
- title: Changelog.jl changelog
- intro: All notable changes to this project will be documented in this file.
- 2 versions:
  - 1.1.0
    - url: https://github.com/JuliaDocs/Changelog.jl/releases/tag/v1.1.0
    - date: 2023-11-13
    - changes
      - Added
        - Links of the form `[<commit hash>]`, where `<commit hash>` is a commit hashof length 7 or 40, are now linkified. (#4)
  - 1.0.0
    - url: https://github.com/JuliaDocs/Changelog.jl/releases/tag/v1.0.0
    - date: 2023-11-13
    - changes
      - First release. See README.md for currently supported functionality.

The changes for 1.1.0 can be obtained by changelog.versions[1].sectioned_changes:

julia> changelog.versions[1].sectioned_changes
1-element Vector{Pair{String, Vector{String}}}:
 "Added" => ["Links of the form `[<commit hash>]`, where `<commit hash>` is a commit hashof length 7 or 40, are now linkified. (#4)"]