Add CHANGELOG.md (#306)

ytdHuang · web-flow · commit 8d1717a9fddb · 2024-11-13T14:50:52.000+01:00
* add CHANGELOG.md

* fix typos

* remove subsubsections in `CHANGELOG.md`

* update PR template

* rename `change_log` as `changelog`

* fix typo

* fix typo

* minor changes
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,11 +1,12 @@
 ## Checklist
 Thank you for contributing to `QuantumToolbox.jl`! Please make sure you have finished the following tasks before opening the PR.
 
-- [ ] Please read [Contributing to QuantumToolbox.jl](https://qutip.org/QuantumToolbox.jl/stable/resources/contribute).
+- [ ] Please read [Contributing to QuantumToolbox.jl](https://qutip.org/QuantumToolbox.jl/stable/resources/contributing).
 - [ ] Any code changes were done in a way that does not break public API.
 - [ ] Appropriate tests were added and tested locally by running: `make test`.
 - [ ] Any code changes should be `julia` formatted by running: `make format`.
 - [ ] All documents (in `docs/` folder) related to code changes were updated and able to build locally by running: `make docs`.
+- [ ] (If necessary) the `CHANGELOG.md` should be updated (regarding to the code changes) and built by running: `make changelog`.
 
 Request for a review after you have completed all the tasks. If you have not finished them all, you can also open a [Draft Pull Request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) to let the others know this on-going work.
 
diff --git a/.github/workflows/ChangeLogCheck.yml b/.github/workflows/ChangeLogCheck.yml
@@ -0,0 +1,14 @@
+# Enforces the update of the file CHANGELOG.md on every pull request
+# Can be skipped with the `Skip ChangeLog` label
+name: ChangeLog Update Check
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled]
+
+jobs:
+  changelog:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: dangoslen/changelog-enforcer@v3
+      with:
+        skipLabels: 'Skip ChangeLog'
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,21 @@
+# ChangeLog
+
+All notable changes to [`QuantumToolbox.jl`](https://github.com/qutip/QuantumToolbox.jl) will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+- *__We will start to write changelog once we have the first standard release.__*
+
+## [v0.21.4] (2024-11-13)
+
+- This is just a demonstration about [`Changelog.jl`](https://github.com/JuliaDocs/Changelog.jl). ([#139], [#306])
+
+
+<!-- Links generated by Changelog.jl -->
+
+[v0.21.4]: https://github.com/qutip/QuantumToolbox.jl/releases/tag/v0.21.4
+[#139]: https://github.com/qutip/QuantumToolbox.jl/issues/139
+[#306]: https://github.com/qutip/QuantumToolbox.jl/issues/306
diff --git a/Makefile b/Makefile
@@ -2,9 +2,15 @@ JULIA:=julia
 
 default: help
 
+setup:
+	${JULIA} -e 'import Pkg; Pkg.add(["JuliaFormatter", "Changelog"])'
+
 format:
 	${JULIA} -e 'using JuliaFormatter; format(".")'
 
+changelog:
+	${JULIA} -e 'using Changelog; Changelog.generate(Changelog.CommonMark(), "CHANGELOG.md"; repo = "qutip/QuantumToolbox.jl")'
+
 test:
 	${JULIA} --project -e 'using Pkg; Pkg.resolve(); Pkg.test()'
 
@@ -16,14 +22,16 @@ vitepress:
 	npm --prefix docs i
 	npm --prefix docs run docs:dev
 
-all: format test docs vitepress
+all: setup format changelog test docs vitepress
 
 help:
 	@echo "The following make commands are available:"
+	@echo " - make setup: install the dependencies for make command"
 	@echo " - make format: format codes with JuliaFormatter"
+	@echo " - make changelog: generate changelog"
 	@echo " - make test: run the tests"
 	@echo " - make docs: instantiate and build the documentation"
 	@echo " - make vitepress: start Vitepress site of documentation"
 	@echo " - make all: run every commands in the above order"
 
-.PHONY: default format test docs vitepress all help
+.PHONY: default setup format changelog test docs vitepress all help
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -2,3 +2,4 @@ build/
 node_modules/
 package-lock.json
 Manifest.toml
+src/resources/changelog.md
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,6 +1,7 @@
 [deps]
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+Changelog = "5217a498-cd5d-4ec6-b8c2-9b85a09b6e3e"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
diff --git a/docs/make.jl b/docs/make.jl
@@ -5,16 +5,26 @@ using QuantumToolbox
 using Documenter
 using DocumenterVitepress
 using DocumenterCitations
+using Changelog
 
 DocMeta.setdocmeta!(QuantumToolbox, :DocTestSetup, :(using QuantumToolbox); recursive = true)
 
 const DRAFT = false # set `true` to disable cell evaluation
 
+# generate bibliography
 bib = CitationBibliography(
     joinpath(@__DIR__, "src", "resources", "bibliography.bib"), 
     style=:authoryear,
 )
 
+# generate changelog
+Changelog.generate(
+    Changelog.Documenter(),
+    joinpath(@__DIR__, "..", "CHANGELOG.md"),
+    joinpath(@__DIR__, "src", "resources", "changelog.md");
+    repo = "qutip/QuantumToolbox.jl",
+)
+
 const PAGES = [
     "Home" => "index.md",
     "Getting Started" => [
@@ -56,8 +66,8 @@ const PAGES = [
     ],
     "Resources" => [
         "API" => "resources/api.md",
-        # "Change Log" => "resources/changelog.md",
         "Bibliography" => "resources/bibliography.md",
+        "ChangeLog" => "resources/changelog.md",
         "Contributing to QuantumToolbox.jl" => "resources/contributing.md",
     ],
 ]
diff --git a/docs/src/resources/contributing.md b/docs/src/resources/contributing.md
@@ -38,6 +38,9 @@ We use [`JuliaFormatter.jl`](https://github.com/domluna/JuliaFormatter.jl) to fo
 
 To format the changed codes, use the following command under the *__root directory of the repository__* you are working on:
 
+!!! note "Requirements"
+    If this is your first time running `make` command in the local repository you are working on or you just had reinstalled `Julia`, you should run `make setup` first.
+
 ```shell
 make format
 ```
@@ -69,4 +72,23 @@ This will start a local Vitepress site of documentation at `http://localhost:517
 
 ## [Update ChangeLog](@id doc-Contribute:Update-ChangeLog)
 
-(TBA)
+The changelog is written in the file `CHANGELOG.md` in the repository. If you add some changes to the repository and made a PR, you should also add some messages or release notes together with the related PRs/issues entries to `CHANGELOG.md`. For example, add a new line in `CHANGELOG.md`:
+
+```markdown
+- some messages to describe the changes. ([#issue-ID], [#PR-ID])
+```
+
+See also the [ChangeLog page](@ref ChangeLog) for more examples.
+
+After that, you can run the following command under the *__root directory of the repository__* you are working on:
+
+!!! note "Requirements"
+    If this is your first time running `make` command in the local repository you are working on or you just had reinstalled `Julia`, you should run `make setup` first.
+
+```shell
+make changelog
+```
+
+This will automatically generate the full URLs for the references to PRs/issues by utilizing [`Changelog.jl`](https://github.com/JuliaDocs/Changelog.jl).
+
+If the changes you made are not necessary to be recorded in `CHANGELOG.md`, you can add the label `[Skip ChangeLog]` to the PR you made in the GitHub repository.
