Add an explicit label to include issue in release notes

[johnsimons]

We have all been there where we run the release notes generator and certain issues appear in the release notes even though we do not want them to.

The current workaround is to either add internal refactoring or remove milestone association.

Workarounds

IMO these workarounds are not appropriate, removing a milestone from an issue that has been addressed in the about to be released version seems wrong, also even if an issue was not fixed but closed as Won't fix that to me should still be associated with a milestone, that is the timeline where we made that decision.
Adding an internal refactoring label so that the issue does not appear in the release notes seem strange too, IMO any "internal refactoring" we do is an "improvement".

Proposed solution

Create a new label called Include in Release Notes, straight to the point.
With this label I believe we do not need an internal refactoring label.
This label puts us in control of what is shown in the release notes and what is not in a much more clear way.

[SeanFeldman]

Support this suggestion. It will allow a fine tuning for release notes w/o loosing milestones or proper labels we have to do now.

In addition to that, PBot will stop bugging on issues that are not marked as Include in Release Notes reducing number of pings caretakers are receiving.

[mauroservienti]

Supposing, correct me if I am wrong, that most of the issues should be included in RN, shouldn't it be Exclude from Release Notes? so that everything is included except what we want to really exclude.

To me it is less prone to errors.

[johnsimons]

That is a good point @mauroservienti, I don't mind either way

[johnsimons]

@Particular/engineers
Is anyone opposed to go ahead with this change ?

[SimonCropp]

@johnsimons

Supposing, correct me if I am wrong, that most of the issues should be included in RN, shouldn't it be Exclude from Release Notes

Isnt this effectively what we have now?

[johnsimons]

It is similar @SimonCropp, but not exactly.
We currently have 2 possible workarounds to exclude issues, with this change we have an explicit way to exclude issues that is not tied to milestones or classification labels.

I am also not sure if having the Exclude from Release Notes instead of Include in Release Notes as proposed originally is the right way to go. My gut feeling is to be explicit all the time to be on the safe side.

[SimonCropp]

with this change we have an explicit way to exclude issues that is not tied to milestones

if the issue is not tied to a milestone then remove it from the milestone. no change required.

[johnsimons]

That is not what I meant @SimonCropp, what I mean is that we do not need to remove the milestone from an issue just because we do not want it to be include in the release notes, I've tried to explain the core reason for this change in the initial description, is the initial description not clear enough ? How can I improve it ?

[SimonCropp]

@johnsimons your description is clear. but the requirement is already met. it seems like a redundant feature

[johnsimons]

@SimonCropp I tend to disagree with that, otherwise the workarounds mentioned would not be required.

The proposal is to make this process easy to follow and more intuitive for anyone, do you consider the current process friendly ?

[gbiellem]

I like the fact that adding something to a milestone defaults it to being in the release notes and I don't see another label as necessary.

@johnsimons makes a good point regarding "won't fix" and timelines but i think it would weird to see these appear in the release notes in any form - Perhaps allow them to be in the milestone but just filter them out of the release notes

[SimonCropp]

also even if an issue was not fixed but closed as Won't fix that to me should still be associated with a milestone

This makes no sense to me. anything decided to not be fixed make no more sense being in one milestone or another. if we "wont fix" an issue it should be removed from the milestone.

[johnsimons]

@gbiellem regarding:

Perhaps allow them to be in the milestone but just filter them out of the release notes

I like that, so the Won't fix label gets excluded from release notes

[SimonCropp]

@johnsimons No. we are not putting "wont fix" issues in milestones

[gbiellem]

Wont fix in milesones seems wrong though.... Can't we just look at the closed date for a timeline

[johnsimons]

Can't we just look at the closed date for a timeline

Not in a easy way @gbiellem, I still think it adds value to associate it with a milestone, what do you see as wrong about that association ?

[johnsimons]

No. we are not putting "wont fix" issues in milestones

Thanks @SimonCropp for your feedback, we are still discussing as a group

[gbiellem]

what do you see as wrong about that association ?

To me a milestone is a record of what we did, not what we decided was not worth doing.

[johnsimons]

Anyway we seem to be de-railing the proposal, the initial concern still stands, at the moment there are inefficient workaround to handle what is include/excluded from release notes, this proposal is to standardise on a way to exclude issues from the release notes without compromising the categorisation and association with a milestone.

[SimonCropp]

we either decide to fix an issue, and hence put it into a milestone. or decide not to fix it in which case we mark as "Wont Fix". It simply makes no sense to mix the two

[SimonCropp]

this proposal is to standardise on a way to exclude issues from the release notes without compromising the categorisation and association with a milestone.

we already have a standardised way. you are just proposing a different way

[johnsimons]

I'm 👍 to adopt @mauroservienti suggestion of adding a new label Exclude from Release Notes

[johnsimons]

we already have a standardised way

Which way is that ? You mean the workarounds ?

[andreasohlund]

So we are proposing to rename Internal refactoring to Exclude from Release Notes?

This has been working for us for a long time and is documented in the readme?

I don't see the ROI here we still need to train people to use Exclude from Release Notes.

Are there other thing that are a higher prio here? Like running the ReleaseNotesCompiler everytime an issue is closed to give early feedback and link to the mentioned doco above?

[johnsimons]

@andreasohlund yes the workaround is documented, but IMHO is not intuitive at all.
The proposal is to make it clear, so we do not even need to document it ;)

Anyway if the majority believes this is a waste of time, I'll close the issue and keep on applying workarounds.

[gbiellem]

@johnsimons how about adding validation to pbot to warn if a won't fix is in a milestone. i.e match pbot validation to the release notes compiler validation

[gep13]

@johnsimons @gbiellem you might be interested to take a look at a project I have been working on:

https://github.com/gep13/GitHubReleaseManager

With the backing of the guys at Particular (https://github.com/gep13/GitHubReleaseManager#credits) I have created a configurable version of GitHubReleaseNotes (as well as adding a few more features as described here GitTools/GitReleaseManager#24 (comment)).

This uses a YAML configuration file, similar to what you will find here:

https://github.com/chocolatey/ChocolateyGUI/blob/develop/GitHubReleaseManager.yaml

As you will see in the above, you are able to configure the names of the labels that you want to be included in the generated release notes, as well as those that are part of the milestone, but which you don't want to include in the generated release notes.

I would love to hear any feedback that you have on the project, and any other features that you would like to see added.

If you want to give it a try, you can run either of the following commands, and it should get you started:

Chocolatey < 0.9.8.33
install GitHubReleaseManager.Portable -pre -source https://www.myget.org/F/ghrm_develop/

Chocolatey = 0.9.8.33
choco install GitHubReleaseManager.Portable -pre -y -source https://www.myget.org/F/ghrm_develop/

Chocolatey 0.9.9.x
choco install GitHubReleaseManager.Portable -pre -y -s https://www.myget.org/F/ghrm_develop/ -n

Once installed, simply run:

githubreleasemanager.cli

to see the available options

(If you are interested in th
e differences between the three commands, happy to discuss offline. Safe to say that Chocolatey is making huge strides forward, and as a result, things are changing 😸)

Let me know if you have any questions.

[SeanFeldman]

Looks like this thread became dormant with no actual action items.
The issue I'm facing is when we have a hotfix for example, and there was a bug introduced and fixed during hotfix. I'd like to have a GH issue with a lable bug and milestone it was in, but not to have it appearing in release notes. As of now, it's a manual process, and the person that does the release notes has to know that an issue was an "internal bug" and shouldn't go out as an announcement.

The suggestion above to tag such an issue with a label is good. I just also remember how many times we had labels changing... Perhaps instead of relying on the labels, use the content. Similar to what we do with the mandatory sections. Just for "internal" bugs/improvements have an entry that would indicate so. E.g. an issue marked as a bug for the currently deployed milestone 7.0.2 would contain in its description the following:

@#internal we fixed the optimization introduced in hotfix 7.0.2 itself

GitHubReleaseNotes would pick the items and not add it, as it's an internal issue. When going through the issues, we can locate the bugs fixed in 7.0.2 and we'll know why an internal issue was not in the notes.

Thoughts?

/cc @danielmarbach

[danielmarbach]

Talked to @timbussmann today about the feature and we realized that we would essentially be abusing text instead of a label because we want to avoid labels. The downside of that would be that when we need to update it we can't just bulk assign a new label but we would need to hand edit all the issues using that specific text which is much more cumbersome.

[SeanFeldman]

Fair point @danielmarbach.
I'm good with a label as well, as long as we don't have to tweak the auto-generated release notes.

[danielmarbach]

Talked to @Particular/nservicebus-maintainers, we are currently staying with the following approach:

We assign all issues and PRs to the milestone they belong to (except if we have an issue and a PR for the same thing) and then we use the release notes compiler to create the first draft and manually filter out things that we don't want in the release notes. At the moment we don't need an additional layer of filtering.

[SeanFeldman]

@danielmarbach should we involve other maintainers and not just @Particular/nservicebus-maintainers ?

I'm ok with the manual approach. It leaves some room for potential mistakes (human error).

[bording]

@SeanFeldman The point is that for core, we've decided to try out this new approach, but that doesn't mean other maintainers have to do the same thing. If you'd prefer to stay with the existing approach, AFAIK the release notes generator should still work fine.

[SeanFeldman]

@bording what's the current approach? Not to include an issue in a milestone? That's the issue, that I would like to label and assign milstone. Don't want the item to show in release notes if it's an internal one.

[bording]

@bording what's the current approach? Not to include an issue in a milestone? That's the issue, that I would like to label and assign milstone. Don't want the item to show in release notes if it's an internal one.

That's what I get for not reading all the way through the issue before posting, my comment was just in context of what the core maintainers have changed to be doing compared to the way things were before, needing to remove items from the milestone.

Sorry for the confusion!

[SeanFeldman]

@bording no worries at all. That's why we have a discussion :)