doc: restructure changelog

CONTRIBUTING.md

@@ -36,12 +36,15 @@ Our development process is as follows:
   Exchanges in meetings and chat are valuable, but we insist on deliberating and
   recording the what and why of our work in the persistent record of GitHub.
 - Changes are submitted via GitHub pull requests against the `main` branch.
+- Technical changes must appear in the project Changelog. Learn more on how to
+  [update the changelog][update changelog].
 
 If you are looking to get started, check our issues tagged with [good first
 issue][good first issue] or [help wanted][help wanted].
 
 [good first issue]: https://github.com/ocaml/dune/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22
 [help wanted]: https://github.com/ocaml/dune/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22
+[update changelog]: https://github.com/ocaml/dune/blob/main/CONTRIBUTING.md#updating-the-changelog
 
 Developer documentation
 -----------------------
@@ -131,3 +134,40 @@ you have the rights to submit this work under the same open source license.
 [js]: https://www.janestreet.com/
 [tarides]: https://tarides.com/
 [hack]: ./doc/hacking.rst
+
+Updating the Changelog
+----------------------
+
+In Dune, the Changelog is in `CHANGES.md`. As there are many contributions at
+the same time and to prevent an infinite cycle of rebases, the `CHANGES.md`
+file is only updated when releasing Dune. Unreleased changes are recorded
+inside `doc/changes/`. The name of the file is `<PR number>.md`. Depending on
+the nature of the change, it can live inside three categories: `added`,
+`changed`, `fixed`, where:
+- `added` records every new feature or behaviour visible to users
+- `changed` records a difference of behaviour with the previous version
+- `fixed` records any change that restores the behaviour as expected
+
+An entry follows this format where `fixes` is optional if it is not linked to
+any issue:
+
+```markdown
+- A small description about what this entry is doing and what this changes
+  brings to the users. Try to imagine what people will understand when reading
+  the changelog. (#<PR number>, fixes #<issue number>, @author1, @author2)
+```
+
+The entry must fit in 80 columns of text. Most of the editors allows formatting
+the size of the text using a column size.
+
+In Dune, we try to avoid breaking changes by versioning our features with a
+`(lang dune <version>)` system. However, if the change you introduce is a
+breaking change, the entry must start with **BREAKING CHANGE:**. The entry
+would be:
+
+```markdown
+- BREAKING CHANGE: A small description about what this entry is doing and what
+  this changes brings to the users. Try to imagine what people will understand
+  when reading the changelog. (#<PR number>, fixes #<issue number>, @author1,
+  @author2)
+```

doc/changes/added/11963.md

@@ -0,0 +1,4 @@
+- (Experimental): Introduce the `library_parameter` stanza. It allows users to
+  declare a parameter when using the OxCaml compiler.
+  (#11963, implements #12084, @maiste) 
+

doc/changes/12064.md → doc/changes/added/12064.md

@@ -1,5 +1,3 @@
-## Added
-
 - Allow `dune fmt` to properly run while a watch mode server is running.
   Note that the `--preview` flag is not supported in this mode.
   (#12064, @ElectreAAS)

doc/changes/12074.md → doc/changes/added/12074.md

@@ -1,2 +1,2 @@
 - Use copy-on-write (COW) when copying files on filesystems that support it
-  (Btrfs, ZFS, XFS, etc), under Linux. (#12074, fixes #12071, @nojb)
+  (Btrfs, ZFS, XFS, etc), under Linux. (#12074, fixes #12071, @nojb)

doc/changes/added/12094.md

@@ -0,0 +1,2 @@
+- `dune exec` now accepts absolute paths inside the workspace.
+  (#12094, @Alizter)

doc/changes/12438.md → doc/changes/added/12438.md

@@ -1 +1,2 @@
-- Add support for `DUNE_ROOT` environment variable, similar to the existing `--root` CLI parameter. (fixes #12399 @sir4ur0n)
+- Add support for `DUNE_ROOT` environment variable, similar to the existing
+  `--root` CLI parameter. (fixes #12399 @sir4ur0n)

doc/changes/changed/11865.md

@@ -0,0 +1,4 @@
+- `dune format-dune-file` now uses the syntax version of the Dune project that
+  contains the file being formatted (if any) instead of using the latest version
+  available, which remains the default if there is no Dune project in scope.
+  (#11865, @nojb)

doc/changes/changed/12227.md

@@ -0,0 +1,2 @@
+- Don't run `ocamldep` to compute false dependencies on the `root_module`
+  (#12227, @rgrinberg)

doc/changes/12299.md → doc/changes/fixed/12299.md

@@ -1,2 +1,2 @@
 - Fix: include the module alias in the transitive dependency closure with
-  `(include_subdirs qualified). (#12299, @anmonteiro)
+  `(include_subdirs qualified)`. (#12299, @anmonteiro)