diff --git a/Makefile b/Makefile index 863e7a918d26..4a7b757771af 100644 --- a/Makefile +++ b/Makefile @@ -87,6 +87,16 @@ dev-switch: opam switch create -y . $(TEST_OCAMLVERSION) --deps-only --with-test opam install -y --update-invariant ocaml.$(TEST_OCAMLVERSION) $(TEST_DEPS) $(DEV_DEPS) +.PHONY: changelog +changelog: + $(BIN) exec -- doc/changes/add.exe + +.PHONY: compile-changelog +compile-changelog: + - $(BIN) build @doc/changes/compile-changelog + $(BIN) promote + rm -rf doc/changes/unreleased + .PHONY: test test: $(BIN) $(BIN) runtest diff --git a/doc/changes/add.ml b/doc/changes/add.ml new file mode 100644 index 000000000000..f3dacec5c3c6 --- /dev/null +++ b/doc/changes/add.ml @@ -0,0 +1,46 @@ +open Stdune +module Console = Dune_console + +(** This script generates a changelog entry for a PR. It asks the user for + information about the pull request and then generates a file in the + [output_directory]. *) + +let output_directory = + Path.source (Path.Source.of_string "doc/changes/unreleased") + +let () = + Console.printf "Hello, let's create a changelog entry!"; + Console.printf "What is the change about?"; + let description = read_line () in + Console.printf "PR number? (Leave blank if you don't know)"; + let pr_number = + match read_line () with + | "" -> "????" + | s -> s + in + Console.printf "What is your username?"; + let username = read_line () in + Console.printf "Which issue numbers does this change fix?"; + let issues = + match read_line () with + | "" -> "" + | s -> + String.split ~on:' ' s + |> List.map ~f:(fun s -> "#" ^ s) + |> String.enumerate_and + |> fun x -> ", fixes " ^ x + in + let pp = + Pp.concat + [ Pp.verbatim "- " + ; Pp.box + (Pp.textf "%s (#%s%s, @%s)" description pr_number issues username) + ; Pp.newline + ] + in + let entry_file = + Path.append_source output_directory + (Path.Source.of_string (pr_number ^ "_" ^ username)) + in + Path.mkdir_p output_directory; + Io.write_lines entry_file [ Format.asprintf "%a" Pp.to_fmt pp ] diff --git a/doc/changes/add.t b/doc/changes/add.t new file mode 100644 index 000000000000..991fccb385d1 --- /dev/null +++ b/doc/changes/add.t @@ -0,0 +1,50 @@ +Testing the changelog adding script + + $ cat > user_response << EOF + > Changelog description that is long enough to be wrapped to the next line + > 1234 + > SomeGithubUser + > 123 456 789 + > EOF + + $ ./add.exe < user_response + Hello, let's create a changelog entry! + What is the change about? + PR number? (Leave blank if you don't know) + What is your username? + Which issue numbers does this change fix? + + $ ls doc/changes/unreleased + 1234_SomeGithubUser + $ cat doc/changes/unreleased/* + - Changelog description that is long enough to be wrapped to the next line + (#1234, fixes #123, #456 and #789, @SomeGithubUser) + + +Testing some edge cases + + $ cat > user_response << EOF + > Changelog description that is long enough to be wrapped to the next line. \ + > This one takes teh cake for being especially long. + > + > AnotherUser + > + > EOF + + $ ./add.exe < user_response + Hello, let's create a changelog entry! + What is the change about? + PR number? (Leave blank if you don't know) + What is your username? + Which issue numbers does this change fix? + + $ ls doc/changes/unreleased + 1234_SomeGithubUser + ????_AnotherUser + $ cat doc/changes/unreleased/* + - Changelog description that is long enough to be wrapped to the next line + (#1234, fixes #123, #456 and #789, @SomeGithubUser) + + - Changelog description that is long enough to be wrapped to the next line. + This one takes teh cake for being especially long. (#????, @AnotherUser) + diff --git a/doc/changes/dune b/doc/changes/dune new file mode 100644 index 000000000000..e71271c44987 --- /dev/null +++ b/doc/changes/dune @@ -0,0 +1,25 @@ +(executable + (name add) + (libraries stdune pp dune_console)) + +(cram + (deps add.exe)) + +(rule + (alias compile-changelog) + (deps + (glob_files unreleased/*)) + (action + (with-stdout-to + changes-new.md + (progn + (echo "Unreleased\n") + (echo "----------\n") + (echo "\n") + (cat %{deps}) + (cat ../../CHANGES.md))))) + +(rule + (alias compile-changelog) + (action + (diff ../../CHANGES.md changes-new.md))) diff --git a/doc/hacking.rst b/doc/hacking.rst index 9ab8e7d9e78b..752b9ce469fb 100644 --- a/doc/hacking.rst +++ b/doc/hacking.rst @@ -389,6 +389,18 @@ For project names, use the following capitalization: - **PPX,** rather than ppx or Ppx; ``ppxlib`` - **UTop,** rather than utop or Utop. +Changelog +========= + +All changes observable by the user should be documented in the changelog. + +Use ``make changelog`` to run an interactive script for adding a changelog +entry. Unreleased changes are collected in their own files in the +``doc/changes/unreleased`` directory. + +During the release process, the changelog entries will be compiled into +``CHANGES.md``. + Vendoring =========