-
Notifications
You must be signed in to change notification settings - Fork 63
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document release process and common labels #425
base: master
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -57,3 +57,43 @@ the ``use-next-minor-as-default-branch`` switch for the | |
$ git switch --create 2.0.x 2.0.0 | ||
Switched to a new branch "2.0.x" | ||
$ git push doctrine 2.0.x | ||
|
||
Tagging a release | ||
----------------- | ||
|
||
We use ``laminas/automatic-releases`` to make releasing as easy as | ||
closing a milestone. Before closing a milestone, one should check that | ||
it is complete. If not, they should unassign issues and pull requests, | ||
or close them / merge them as appropriate. It is also a good idea to | ||
check which pull requests were merged since the last release on the | ||
relevant branch, and to make sure each one is properly labelled and | ||
assigned to the milestone. | ||
|
||
Labels are used to generate the release notes, and we should strive to | ||
provide a consistent experience accross repositories. Here are labels | ||
that we recommend adding on every repository: | ||
|
||
BC Break | ||
Changes or removals that may require changes or actions from the user | ||
before the package can be used again. | ||
|
||
Improvement | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. To be preferred over "New Feature" or "Enhancement" then? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I would say so. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. My vote goes for "Feature". "New" part in new "New feature" is useless, we won't be adding old features ;) |
||
Additions to the feature set or API of the package that are backward | ||
compatible | ||
|
||
Bugfix | ||
Changes that fix an issue affecting the user of the package. | ||
|
||
Documentation | ||
Includes changes to rst files, markdown files as well as code | ||
comments. | ||
|
||
Deprecation | ||
For pull requests that *introduce* a new deprecation (as opposed to | ||
addressing deprecations from another package, or removing deprecated | ||
code paths) | ||
|
||
Internal | ||
Changes that do not impact the end user, but might impact contributors | ||
or maintainers, such as improvements to the CI, bugfixes for the test | ||
suite, etc. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMO, we're jumping right to the solution w/o the due statement of the problem. Why do we even use them in release notes? Why should labels be consistent across repositories? To what extent should they be consistent? What else are labels used for?
It's hard to discuss the solution to the problem that I personally don't understand. As a single-repository maintainer, I mostly use labels for navigation and grouping of related issues. Should we define the scope of this discussion? E.g. which labels should be considered common and which shouldn't?
So far, the only aspect common to all repositories that comes to mind is the upgrade impact (i.e. what the users should expect to be fixed, what's deprecated, and so on). Are there any other common aspects?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good question! Our release notes do not look like the ones on https://keepachangelog.com/en/1.0.0/
I can find old releases that have a format consistent with the one we are currently using, although they were definitely not relying on
laminas/automatic-releases
.laminas/automatic-release
relies on https://github.com/jwage/changelog-generator , so that's probably what was used:The other predominant format was one that simply mentioned the number of issues resolved:
I'd say right now we are using labels in release notes to be consistent with the format above, but I don't know the original reason.
I think labels that have the same name should be understood the same way across repositories, so that it's easier to maintain any Doctrine repository. Personally, I've noticed that's sometimes I'm looking for some label in the list, and don't know which to pick. Sometimes "Enhancement" is present, sometimes you have "Improvement"… it's a bit confusing.
Yes, definitely. Maybe we should only discuss labels that are put on PRs, since they are the ones we are using for generating the changelog
Nothing comes to mind, but yes the upgrade impact is indeed something we will want to make clear to our users regardless of the repository.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
From the upgrade impact standpoint, the categories defined in the "keepachangelog" make sense to me, and I wouldn't reinvent the wheel.
On the other hand, as far as I can tell, such changelogs are generated manually by committing changes in the changelog to Git. To me, this would be annoying and actually look like an abuse of the VCS which already keeps track of the changes.
Are there examples of maintaining a changelog like this via labels?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't have an example in mind no. People don't tend to label PRs with
Added
,Removed
. The past tense seems weird here, and also a single PR can contain several additions and removals.Fully agree, having a
CHANGELOG.md
file seems weird to me also, having a/releases
endpoint does the job quite well. To me, both things are the same, only the medium changes.I think they do make sense, but that we should map them to labels, because labeling a PR with
Added
feels weird. I don't think that we can actually map labels to categories, but IMO it's not bad at all to have "New Feature" or "Deprecation" as a category.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This implicit mapping is a slippery slope. I believe the whole point of keeping the changelog is to keep it explicitly and manually. Only a human can decompose an arbitrary set of label combinations into a human-friendly log.
So I believe, we should either use labels w/o trying to adopt the "keepachangelog" principle, or we do it manually (looks like too much work).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If by that you mean using "New Feature", "BC Break" etc. as opposed to "Added", "Changed", etc. Then that sounds good to me, but I'm not sure if that's what you mean because it just seems like different labels but the same principle: letting the user know about the upgrade impact.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, let's use just these labels. Maybe we could replace the "New Feature" with a more general "Improvement".
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just to chime in before writing in detail how we manage this in ODM, I'm personally for "Feature" rather than "Improvement". Multiple things can be improved: performance, DX, API. When we're adding a new feature it's, well, a "Feature" :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
True. A Feature is an Improvement but an Improvement is not necessarily a feature.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"Improvement" does feel a bit like it might be an internal feature