Document release process and common labels

[greg0ire]

Inspired from https://github.com/orgs/doctrine/teams/doctrinecore/discussions/2

[SenseException]

I remember we had a topic about unified labels a long time ago somewhere on GitHub, but I didn't find it quickly.

[greg0ire]

I remember we had a topic about unified labels a long time ago somewhere on GitHub, but I didn't find it quickly.

Sorry, I should have mentioned it. I put it in the description.

[greg0ire]

@morozov @malarzm since you were involved in the previous discussion, I'm requesting your review as well.

[driehle]

Not that I want to interrupt you guys in any way, just a short notice that the four repositories for the Laminas integrations already have their labels standardized. We are using the same labels als laminas does on their repositories, see e.g. https://github.com/doctrine/DoctrineModule/labels. So far, I haven't missed anything there.

[driehle]

Furthermore, I'd like to point to label-syncer, which could be set up in the .github repository to synchronize labels across all Doctrine repositories. The set of labels used in the Laminas-related repositories can be found here. I'd suggest adding such a file to the .github repository, once the discussion about the labels has settled.

[SenseException]

That's a nice one :+1:

[malarzm]

First things first, list of label we're using in ODM (https://github.com/doctrine/mongodb-odm/labels) filtered to what we're slapping on PRs (sometimes also on issues, not the point):

• BC Break - PR introducing a BC Break
• Bug - bug fixes (or bugs when used on issue)
• Documentation - documentation additions, rewritings, and general maintenance
• Enhancement - I hoped we're not using this, but apparently we do. Mostly could be divided into features and tasks from what I see
• Feature - PR introducing a new feature to the library
• Task - internal doings, such as CI, static analysis, tests. Generally speaking changes not important from a userland perspective.

Comparing with currently discussed list:

• BC Break - we're on the same page
• Improvement - Feature is our counterpart and as voiced in comments my proffered choice
• Bugfix - we use Bug and the reasoning would be because we're also marking issues as such.
• Documentation - match
• Deprecation - we're not currently using label for this kind of change, but we could start
• Internal - Task is our counterpart, I'm open to changing it

Apart from few name differences (and possible quarrels ;) we're good 👍

We also maintain UPGRADE-x.y.md files. PRs that are adding deprecations to the code MUST also add a note in an UPGRADE file related to the version they land in. The UPGRADE file is mostly why we're not using "Deprecation" label, the files are maintained since forever and I tend to think users do know about them :) In a similar manner, PRs marked as BC break MUST also make an addition to the related UPGRADE file, usually they're stating the same thing as their deprecation-pr-counterpart.

I believe our UPGRADE file policy is also used across other repositories, but since we're trying to standardize labels, those rules also should be included.

Also on a closing note: I'm not sure if standardizing labels is a worthwhile thing to do. I'm not saying this to diminish the effort, but because I believe the gain will not be worth the time we invest in discussing this back and forth. Our most important repositories have a group of regular maintainers that can always be consulted or just change labels that were added in a wrong manner. For our important but smaller repositories that are maintained by whoever-has-some-willpower-currently well, inconsistent labeling is least important issue for those repositories ;)

[greg0ire]

we use Bug and the reasoning would be because we're also marking issues as such.

Is there a point in doing that? I think Bugfix would look better in release notes.

I'm not sure if standardizing labels is a worthwhile thing to do. I'm not saying this to diminish the effort, but because I believe the gain will not be worth the time we invest in discussing this back and forth. Our most important repositories have a group of regular maintainers that can always be consulted or just change labels that were added in a wrong manner. For our important but smaller repositories that are maintained by whoever-has-some-willpower-currently well, inconsistent labeling is least important issue for those repositories

It's not super important indeed, but I think we are close to an agreement, given your answer, and given the restricted scope of this.

[driehle]

Is there a point in doing that? I think Bugfix would look better in release notes.

I think so, yes. I tend to link issues against milestones as well, so that they appear in the release notes. Sometimes there is more information available in the issues than there is in a pull request, where the PR is rather on technical aspects (code reviews, please rebase, squash, fix cs issues, etc.) which are not relevant for users. In contrast, issues may hold the discussion on conceptual aspects or how users need to migrate their code. So, yes, I think there are valid reasons for assigning labels to issues and linking issues to milestones.

[greg0ire]

@driehle yes but is there a point in marking both issues reporting bugs and PRs fixing them as "Bug"? Won't it be confusing to have both under the same section?

[malarzm]

@greg0ire

Is there a point in doing that? I think Bugfix would look better in release notes.

@driehle pointed it out really well :)

yes but is there a point in marking both issues reporting bugs and PRs fixing them as "Bug"? Won't it be confusing to have both under the same section?

I believe our bugfix relases are small enough to not confuse people ;)

It's not super important indeed, but I think we are close to an agreement, given your answer, and given the restricted scope of this.

Fingers crossed!