Use Changelog.jl for changelog generation (#1061)

This patch replaces the custom changelog code with Changelog.jl for
changelog generation. In addition, a link to the changelog is added to
the HTML documentation. Closes #925.

docs/Manifest.toml

@@ -1,8 +1,8 @@
 # This file is machine-generated - editing it directly is not advised
 
-julia_version = "1.10.4"
+julia_version = "1.10.5"
 manifest_format = "2.0"
-project_hash = "2283fea1dfcfa0f2c82cdecbc5750875c26d6009"
+project_hash = "864d1d29886fc101f4919a6d1c30efd8f4e2ca2e"
 
 [[deps.ADTypes]]
 git-tree-sha1 = "ae44a0c3d68a420d4ac0fa1f7e0c034ccecb6dc5"
@@ -177,6 +177,11 @@ weakdeps = ["SparseArrays"]
     [deps.ChainRulesCore.extensions]
     ChainRulesCoreSparseArraysExt = "SparseArrays"
 
+[[deps.Changelog]]
+git-tree-sha1 = "e579c6157598169ad4ef17263bdf3452b4a3e316"
+uuid = "5217a498-cd5d-4ec6-b8c2-9b85a09b6e3e"
+version = "1.1.0"
+
 [[deps.CloseOpenIntervals]]
 deps = ["Static", "StaticArrayInterface"]
 git-tree-sha1 = "05ba0d07cd4fd8b7a39541e31a7b0254704ea581"

docs/Project.toml

@@ -1,5 +1,6 @@
 [deps]
 BlockArrays = "8e7c35d0-a365-5155-bbbb-fb81a777f24e"
+Changelog = "5217a498-cd5d-4ec6-b8c2-9b85a09b6e3e"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 Ferrite = "c061ca5d-56c9-439f-9c0e-210fe06d3992"

docs/changelog.jl

@@ -1,53 +1,7 @@
-const changelogfile = joinpath(@__DIR__, "../CHANGELOG.md")
+using Changelog
 
-function create_documenter_changelog()
-    content = read(changelogfile, String)
-    # Replace release headers
-    content = replace(content, "## [Unreleased]" => "## Changes yet to be released")
-    content = replace(content, r"## \[(\d+\.\d+\.\d+)\]" => s"## Version \1")
-    # Replace [#XXX][github-XXX] with the proper links
-    content = replace(content, r"(\[#(\d+)\])\[github-\d+\]" => s"\1(https://github.com/Ferrite-FEM/Ferrite.jl/pull/\2)")
-    # Remove all links at the bottom
-    content = replace(content, r"^<!-- Release links -->.*$"ms => "")
-    # Change some GitHub in-readme links to documenter links
-    content = replace(content, "(#upgrading-code-from-ferrite-03-to-10)" => "(@ref)")
-    # Add a contents block
-    last_sentence_before_content = "adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)."
-    contents_block = """
-    ```@contents
-    Pages = ["changelog.md"]
-    Depth = 2:2
-    ```
-    """
-    content = replace(content, last_sentence_before_content => last_sentence_before_content * "\n\n" * contents_block)
-    # Remove trailing lines
-    content = strip(content) * "\n"
-    # Write out the content
-    write(joinpath(@__DIR__, "src/changelog.md"), content)
-    return nothing
-end
-
-function fix_links()
-    content = read(changelogfile, String)
-    text = split(content, "<!-- Release links -->")[1]
-    # Look for links of the form: [#XXX][github-XXX]
-    github_links = Dict{String, String}()
-    r = r"\[#(\d+)\](\[github-(\d+)\])"
-    for m in eachmatch(r, text)
-        @assert m[1] == m[3]
-        # Always use /pull/ since it will redirect to /issues/ if it is an issue
-        url = "https://github.com/Ferrite-FEM/Ferrite.jl/pull/$(m[1])"
-        github_links[m[2]] = url
-    end
-    io = IOBuffer()
-    print(io, "<!-- GitHub pull request/issue links -->\n\n")
-    for l in sort!(collect(github_links); by = first)
-        println(io, l[1], ": ", l[2])
-    end
-    content = replace(content, r"<!-- GitHub pull request/issue links -->.*$"ms => String(take!(io)))
-    write(changelogfile, content)
-end
-
-if abspath(PROGRAM_FILE) == @__FILE__
-    fix_links()
-end
+Changelog.generate(
+    Changelog.CommonMark(),
+    joinpath(@__DIR__, "..", "CHANGELOG.md");
+    repo = "Ferrite-FEM/Ferrite.jl",
+)

docs/make.jl

@@ -10,7 +10,8 @@ if liveserver
     @timeit dto "Revise.revise()" Revise.revise()
 end
 
-using Documenter, DocumenterCitations, Ferrite, FerriteGmsh, FerriteMeshParser, SparseArrays, LinearAlgebra
+using Documenter, DocumenterCitations, Ferrite, FerriteGmsh, FerriteMeshParser,
+    SparseArrays, LinearAlgebra, Changelog
 
 using BlockArrays
 const FerriteBlockArrays = Base.get_extension(Ferrite, :FerriteBlockArrays)
@@ -21,8 +22,12 @@ const is_ci = haskey(ENV, "GITHUB_ACTIONS")
 include("generate.jl")
 
 # Changelog
-include("changelog.jl")
-create_documenter_changelog()
+Changelog.generate(
+    Changelog.Documenter(),
+    joinpath(@__DIR__, "..", "CHANGELOG.md"),
+    joinpath(@__DIR__, "src", "changelog.md");
+    repo = "Ferrite-FEM/Ferrite.jl",
+)
 
 bibtex_plugin = CitationBibliography(
     joinpath(@__DIR__, "src", "assets", "references.bib"),
@@ -46,7 +51,7 @@ bibtex_plugin = CitationBibliography(
     draft = liveserver,
     pages = Any[
         "Home" => "index.md",
-        # hide("Changelog" => "changelog.md"),
+        hide("Changelog" => "changelog.md"),
         "Tutorials" => [
             "Tutorials overview" => "tutorials/index.md",
             "tutorials/heat_equation.md",

docs/src/index.md

@@ -9,6 +9,11 @@ provides functionalities to implement finite element analysis in
 [Julia](https://github.com/JuliaLang/julia). The aim is to be i) general, ii) performant,
 and iii) to keep mathematical abstractions.
 
+!!! note "Upgrading code from version 0.3.x to version 1.0"
+    Ferrite version 1.0 contains a number of breaking changes compared to version 0.3.x. The
+    [Changelog](changelog.md) documents all changes and there is also a section specifically
+    for [Upgrading code from Ferrite 0.3 to 1.0](@ref).
+
 !!! note
     Please help improve this documentation -- if something confuses you, chances are you're
     not alone. It's easy to do as you read along: just click on the "Edit on GitHub" link at
@@ -36,9 +41,15 @@ for. The document is organized as follows[^1]:
 
 [^1]: The organization of the document follows the [Diátaxis Framework](https://diataxis.fr).
 
-In addition there is a [**Code gallery**](gallery/index.md), with user contributed example
-programs, and the [**Developer documentation**](devdocs/index.md), for documentation of
-Ferrite internal code.
+The four sections above form the main user-facing parts of the documentation. In addition,
+the document also contain the following sections:
+
+ - [**Code gallery**](gallery/index.md) contain user contributed example programs showcasing
+   what can be done with Ferrite.
+ - [**Changelog**](changelog.md) contain release notes and information about how to upgrade
+   between releases.
+ - [**Developer documentation**](devdocs/index.md) contain documentation of Ferrite internal
+   code and is mainly targeted at developers of Ferrite.
 
 ## Getting started