changelog creator

Signed-off-by: Ali Caglayan <alizter@gmail.com>

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

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 ]

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)
+

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)))

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
 =========