diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 69f4780af08..a67ee7af6a7 100644 --- a/CONTRIBUTING.md +++ b/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 `.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. (#, fixes #, @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 )` 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. (#, fixes #, @author1, + @author2) +``` diff --git a/doc/changes/11865.md b/doc/changes/11865.md deleted file mode 100644 index 4210fd27a70..00000000000 --- a/doc/changes/11865.md +++ /dev/null @@ -1,4 +0,0 @@ -- #11865: `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. (@nojb) diff --git a/doc/changes/11963.md b/doc/changes/11963.md deleted file mode 100644 index bed068e33bf..00000000000 --- a/doc/changes/11963.md +++ /dev/null @@ -1,4 +0,0 @@ -## Added - -- (Experimental): Introduce the `library_parameter` stanza. It allows users to declare a parameter when - using the OxCaml compiler (#11963, implements #12084, @maiste) diff --git a/doc/changes/12094.md b/doc/changes/12094.md deleted file mode 100644 index 2b6594eb3e6..00000000000 --- a/doc/changes/12094.md +++ /dev/null @@ -1,2 +0,0 @@ -- `dune exec` now accepts absolute paths inside the workspace. (#12094, - @Alizter) diff --git a/doc/changes/12227.md b/doc/changes/12227.md deleted file mode 100644 index 58ac1e3c95a..00000000000 --- a/doc/changes/12227.md +++ /dev/null @@ -1,2 +0,0 @@ -- Don't run ocamldep to compute false dependencies on the `root_module` - (#12227, @rgrinberg) diff --git a/doc/changes/added/.keep b/doc/changes/added/.keep new file mode 100644 index 00000000000..e69de29bb2d diff --git a/doc/changes/added/11963.md b/doc/changes/added/11963.md new file mode 100644 index 00000000000..12b51097d15 --- /dev/null +++ b/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) + diff --git a/doc/changes/12064.md b/doc/changes/added/12064.md similarity index 94% rename from doc/changes/12064.md rename to doc/changes/added/12064.md index 533f89e990a..0df4bf62aea 100644 --- a/doc/changes/12064.md +++ b/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) diff --git a/doc/changes/12074.md b/doc/changes/added/12074.md similarity index 96% rename from doc/changes/12074.md rename to doc/changes/added/12074.md index 18dc8fc8179..16ae6417519 100644 --- a/doc/changes/12074.md +++ b/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) \ No newline at end of file + (Btrfs, ZFS, XFS, etc), under Linux. (#12074, fixes #12071, @nojb) diff --git a/doc/changes/added/12094.md b/doc/changes/added/12094.md new file mode 100644 index 00000000000..6e2c283442b --- /dev/null +++ b/doc/changes/added/12094.md @@ -0,0 +1,2 @@ +- `dune exec` now accepts absolute paths inside the workspace. + (#12094, @Alizter) diff --git a/doc/changes/12197.md b/doc/changes/added/12197.md similarity index 100% rename from doc/changes/12197.md rename to doc/changes/added/12197.md diff --git a/doc/changes/12236.md b/doc/changes/added/12236.md similarity index 100% rename from doc/changes/12236.md rename to doc/changes/added/12236.md diff --git a/doc/changes/12307.md b/doc/changes/added/12307.md similarity index 100% rename from doc/changes/12307.md rename to doc/changes/added/12307.md diff --git a/doc/changes/12438.md b/doc/changes/added/12438.md similarity index 50% rename from doc/changes/12438.md rename to doc/changes/added/12438.md index a5787c26e01..a6d83f07bba 100644 --- a/doc/changes/12438.md +++ b/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) diff --git a/doc/changes/9793.md b/doc/changes/added/9793.md similarity index 100% rename from doc/changes/9793.md rename to doc/changes/added/9793.md diff --git a/doc/changes/changed/.keep b/doc/changes/changed/.keep new file mode 100644 index 00000000000..e69de29bb2d diff --git a/doc/changes/changed/11865.md b/doc/changes/changed/11865.md new file mode 100644 index 00000000000..bc585957c2a --- /dev/null +++ b/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) diff --git a/doc/changes/changed/12227.md b/doc/changes/changed/12227.md new file mode 100644 index 00000000000..ea4633f5b06 --- /dev/null +++ b/doc/changes/changed/12227.md @@ -0,0 +1,2 @@ +- Don't run `ocamldep` to compute false dependencies on the `root_module` + (#12227, @rgrinberg) diff --git a/doc/changes/12350.md b/doc/changes/changed/12350.md similarity index 100% rename from doc/changes/12350.md rename to doc/changes/changed/12350.md diff --git a/doc/changes/12519.md b/doc/changes/changed/12519.md similarity index 100% rename from doc/changes/12519.md rename to doc/changes/changed/12519.md diff --git a/doc/changes/fixed/.keep b/doc/changes/fixed/.keep new file mode 100644 index 00000000000..e69de29bb2d diff --git a/doc/changes/12239.md b/doc/changes/fixed/12239.md similarity index 100% rename from doc/changes/12239.md rename to doc/changes/fixed/12239.md diff --git a/doc/changes/12299.md b/doc/changes/fixed/12299.md similarity index 57% rename from doc/changes/12299.md rename to doc/changes/fixed/12299.md index f0371ef86cd..1818fe2f55b 100644 --- a/doc/changes/12299.md +++ b/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) diff --git a/doc/changes/12464.md b/doc/changes/fixed/12464.md similarity index 100% rename from doc/changes/12464.md rename to doc/changes/fixed/12464.md diff --git a/doc/changes/12530.md b/doc/changes/fixed/12530.md similarity index 100% rename from doc/changes/12530.md rename to doc/changes/fixed/12530.md