Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Document release process and common labels #425

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Document release process and common labels #425

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions source/contribute/maintainer.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

@morozov morozov Nov 19, 2021 •
edited
Loading

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?

Copy link
Member Author

@greg0ire greg0ire Nov 19, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we even use them in release notes?

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.

Why should labels be consistent across repositories?

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.

Should we define the scope of this discussion? E.g. which labels should be considered common and which shouldn't?

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

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?

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.

Copy link
Member

@morozov morozov Nov 20, 2021 •
edited
Loading

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?

Copy link
Member Author

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.

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.

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.

From the upgrade impact standpoint, the categories defined in the "keepachangelog" make sense to me, and I wouldn't reinvent the wheel.

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.

  • Added => New Feature
  • Changed => ??? Internal? BC Break? That one is unclear to me.
  • Removed => BC Break
  • Deprecated => Deprecation
  • Fixes => Bugfix
  • Security can stay as is

Copy link
Member

@morozov morozov Nov 20, 2021 •
edited
Loading

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So I believe, we should either use labels w/o trying to adopt the "keepachangelog" principle

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.

Copy link
Member

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

Yes, let's use just these labels. Maybe we could replace the "New Feature" with a more general "Improvement".

Copy link
Member

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

Copy link
Member

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.

Copy link
Member Author

@greg0ire greg0ire Nov 25, 2021 •
edited
Loading

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

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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be preferred over "New Feature" or "Enhancement" then?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would say so.

Copy link
Member

Choose a reason for hiding this comment

The 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.