From 8d1717a9fddb06d691f84028900dc2d3a109ca53 Mon Sep 17 00:00:00 2001 From: Yi-Te Huang <44385685+ytdHuang@users.noreply.github.com> Date: Wed, 13 Nov 2024 22:50:52 +0900 Subject: [PATCH] Add `CHANGELOG.md` (#306) * add CHANGELOG.md * fix typos * remove subsubsections in `CHANGELOG.md` * update PR template * rename `change_log` as `changelog` * fix typo * fix typo * minor changes --- .github/pull_request_template.md | 3 ++- .github/workflows/ChangeLogCheck.yml | 14 ++++++++++++++ CHANGELOG.md | 21 +++++++++++++++++++++ Makefile | 12 ++++++++++-- docs/.gitignore | 1 + docs/Project.toml | 1 + docs/make.jl | 12 +++++++++++- docs/src/resources/contributing.md | 24 +++++++++++++++++++++++- 8 files changed, 83 insertions(+), 5 deletions(-) create mode 100644 .github/workflows/ChangeLogCheck.yml create mode 100644 CHANGELOG.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7a2a6fd8..c1c968ca 100644 --- 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 new file mode 100644 index 00000000..63458325 --- /dev/null +++ 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' \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..df6e81ce --- /dev/null +++ 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]) + + + + +[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 index 25cf0265..4fd24cfc 100644 --- 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 index 778ffdc1..b3c4f480 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -2,3 +2,4 @@ build/ node_modules/ package-lock.json Manifest.toml +src/resources/changelog.md \ No newline at end of file diff --git a/docs/Project.toml b/docs/Project.toml index ef98b807..078f2ad1 100644 --- 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 index c5a097b5..70d95af7 100644 --- 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 index 31b80092..517191c0 100644 --- 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.