doc: restructure changelog #12472
doc: restructure changelog #12472
Conversation
maiste
added
docs
maiste
force-pushed
the
chore/rewrite-changelog-structure
branch
from
c8eafc4 to
ccc22be
Compare
maiste
force-pushed
the
chore/rewrite-changelog-structure
branch
2 times, most recently
from
d3c6cb5 to
27ee3bc
Compare
|
@Alizter and @shonfeder I have rebased the PR on the |
CONTRIBUTING.md
Outdated
| In Dune, the Changelog is in `CHANGES.md`. As they are many contributions at | ||
| the same time and to prevent an infinite cycle of rebase, the `CHANGES.md` file | ||
| is only updated when releasing Dune. To keep track of the changes, they must be | ||
| recorded inside `doc/changes/`. The name of the file is `<PR number>.md`. |
There was a problem hiding this comment.
Is it actually necessary that the file just be numbered? Can it have a descriptive name too/instead?
There was a problem hiding this comment.
As we only append the files in CHANGES.md and they should be reviewed before being merged into main, it is not necessary to have a descriptive name. Using the number of the PR makes it easier to retrieve when doing patch release (where we want to target small changes).
| `added`, `changed`, `fixed`, where: | ||
| - `added` records every new feature or behaviour inside of Dune | ||
| - `changed` records a difference of behaviour with the previous version | ||
| - `fixed` records any change that restores the behaviour as expected |
There was a problem hiding this comment.
An explanation of the format, with an example, would also be helpful here (including the conventions for referencing the PR and author).
How are breaking changes indicated?
There was a problem hiding this comment.
I don't think we specify the breaking changes, as the SemVer convention is supposed to make this very clear by increasing the major version number.
Even if it is not entirely true (as we have seen with the formatting), dune is "not supposed" to introduce breaking changes without changing the lang dune version.
However, I would be happy to add a convention for such cases. Apart from a BREAKING CHANGE in front of the entry, I don't see anything else. Would you have any suggestion here?
There was a problem hiding this comment.
You're correct that breaking changes are uncommon in dune, in that we do our best to avoid them. Since those cases are rare, I don't think it makes sense to add special support for it. When they do happen we can manually edit the changelog to highlight the severity.
There was a problem hiding this comment.
I pushed a fix with a breaking change part before seeing your comment. Let me know if the wording is not emphasizing enough the exceptional aspect of breaking change. If it does not work, I can remove it.
maiste
force-pushed
the
chore/rewrite-changelog-structure
branch
from
27ee3bc to
ff76db1
Compare
|
Thanks for the review @shonfeder! I have applied your suggestions and reworked the part about the format. I added a paragraph about BREAKING CHANGE. Does it work for you? |
|
Indeed! I expect a period where we will have to manually move the markdown files until the new structure is fully adopted. |
Signed-off-by: Etienne Marais <[email protected]>
maiste
force-pushed
the
chore/rewrite-changelog-structure
branch
from
ff76db1 to
6ff6b56
Compare
Signed-off-by: Etienne Marais <[email protected]>
Signed-off-by: Etienne Marais <[email protected]>
Signed-off-by: Etienne Marais <[email protected]>
maiste
force-pushed
the
chore/rewrite-changelog-structure
branch
from
6ff6b56 to
04bdb1d
Compare
This PR is based on top of the #12440. It must not be merged until the other PR is merged. The PR updates the structure and replaces it with three categories for the Changelog (
added,changedand,fixed). It also updates theCONTRIBUTING.mdwith an explanation on how it works.This PR is the first part of #12304. It will help to generate the changelog in automatically and simplify the release process.
(To be review, you should only take the last three commits into account)