Merge pull request #2035 from JuliaDocs/od/changelog

Refactor CHANGELOG.md to the Keep a Changelog style

.github/workflows/CI.yml

@@ -169,35 +169,3 @@ jobs:
         run: julia --color=yes --project=docs/ docs/instantiate.jl
       - name: Build and check documentation
         run: julia --color=yes --project=docs/ docs/make.jl linkcheck
-
-  changelog:
-    name: "Verify CHANGELOG"
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: julia-actions/setup-julia@latest
-        with:
-          version: '1.6'
-      - name: Install dependencies
-        run: julia --color=yes --project=scripts/ -e 'using Pkg; Pkg.instantiate()'
-      - name: Test scripts/changelog.jl
-        run: |
-          # Run the unit tests of the changelog.jl script:
-          julia --color=yes --code-coverage --project=scripts/ scripts/changelog.jl test
-          # Run changelog.jl with a small, but known good CHANGELOG file and make sure it passes:
-          julia --color=yes --code-coverage --project=scripts/ scripts/changelog.jl --file=scripts/changelog-valid.md
-          # Run changelog.jl with a known _bad_ CHANGELOG file, which should exit with a non-zero code:
-          ! julia --color=yes --code-coverage --project=scripts/ scripts/changelog.jl --file=scripts/changelog-invalid.md
-      - name: Check CHANGELOG.md
-        run: julia --color=yes --code-coverage --project=scripts/ scripts/changelog.jl --github
-      - uses: julia-actions/julia-processcoverage@v1
-        with:
-          directories: src,scripts
-      - uses: codecov/codecov-action@v1
-        with:
-          file: lcov.info
-      - name: Submit coverage to Coveralls
-        uses: coverallsapp/github-action@1.1.3
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          path-to-lcov: lcov.info

.gitignore

@@ -17,3 +17,4 @@ docs/dev/
 docs/build/
 docs/build-pdf/
 docs/site/
+docs/src/release-notes.md

docs/make.jl

@@ -10,6 +10,84 @@ if haskey(ENV, "DOCSARGS")
     end
 end
 
+# ==============================================================================
+#  Modify the release notes
+# ==============================================================================
+
+function fix_release_line(
+    line::String;
+    repo::String = "JuliaDocs/Documenter.jl",
+)
+    # Rule: ((abc#XXXX) -> ([abc#XXXX](https://github.com/abc/issue/XXXX))
+    # Description: Replace issue/PR nnumbers with a link to the default repo
+    # Example: (JuliaLang/julia#123) -> ([JuliaLang/julia#123](https://github.com/JuliaLang/julia/issues/123))
+    # There is no need to distinguish between PRs and Issues because GitHub
+    # redirects.
+    while (m = match(r"\(([a-zA-Z0-9/]+?)\#([0-9]+)\)", line)) !== nothing
+        new_repo, id = m.captures[1], m.captures[2]
+        line = replace(line, m.match => "([$new_repo#$id](https://github.com/$new_repo/issues/$id))")
+    end
+    # Rule: (#XXXX) -> ([#XXXX](https://github.com/url/issue/XXXX))
+    # Description: Replace issue/PR nnumbers with a link to the default repo
+    # Example: (#123) -> ([#123](https://github.com/JuliaDocs/Documenter.jl/issues/123))
+    # There is no need to distinguish between PRs and Issues because GitHub
+    # redirects.
+    while (m = match(r"\(\#([0-9]+)\)", line)) !== nothing
+        id = m.captures[1]
+        line = replace(line, m.match => "([#$id](https://github.com/$repo/issues/$id))")
+    end
+    # Rule: (@XXXX) -> ([@XXXX](https://github.com/XXXX))
+    # Description: Replace users with a link to their GitHub
+    # Example: (@odow) -> ([@odow](https://github.com/odow))
+    while (m = match(r"\(@(.+?)\)", line)) !== nothing
+        id = m.captures[1]
+        line = replace(line, m.match => "([@$id](https://github.com/$id))")
+    end
+    # Rule: ## Version vX.Y.Z -> ## Version [vX.Y.Z](url/releases/tag/vX.Y.Z)
+    # Description: Replace version headers with a link to the GitHub tag
+    # Example: ## Version v0.27.0 -> ## Version [v0.27.0](https://github.com/JuliaDocs/Documenter.jl/releases/tag/v0.27.0)
+    while (m = match(r"\#\# Version (v[0-9]+.[0-9]+.[0-9]+)", line)) !== nothing
+        tag = m.captures[1]
+        line = replace(
+            line,
+            m.match => "## Version [$tag](https://github.com/$repo/releases/tag/$tag)",
+        )
+    end
+    return line
+end
+
+function rewrite_changelog(;
+    changelog_filename::String,
+    release_notes_filename::String,
+    current_module::String,
+    repo::String,
+    branch::String = "master",
+)
+    header = """
+    ```@meta
+    CurrentModule = $current_module
+    EditURL = "https://github.com/$repo/blob/$branch/CHANGELOG.md"
+    ```
+    """
+    open(changelog_filename, "r") do in_io
+        open(release_notes_filename, "w") do out_io
+            write(out_io, header)
+            for line in readlines(in_io; keep = true)
+                write(out_io, fix_release_line(line; repo = repo))
+            end
+        end
+    end
+    return
+end
+
+rewrite_changelog(
+    changelog_filename = joinpath(dirname(@__DIR__), "CHANGELOG.md"),
+    release_notes_filename = joinpath(@__DIR__, "src", "release-notes.md"),
+    current_module = "Documenter",
+    repo = "JuliaDocs/Documenter.jl",
+
+)
+
 makedocs(
     modules = [Documenter, DocumenterTools, DocumenterShowcase],
     format = if "pdf" in ARGS
@@ -63,6 +141,7 @@ makedocs(
             ),
         ],
         "contributing.md",
+        "release-notes.md",
     ],
     strict = !("strict=false" in ARGS),
     doctest = ("doctest=only" in ARGS) ? :only : true,