Particular
Slimmer release notes
Rather than the current release notes format, where we include a section of the body of the issue we should just use the issue title and number like so.
Bugs
- Don't include note about closed issues if there was no issues closed (15)
Features
This is much more compact and easier to read. Plus it requires less validation of the release notes as the body of the issue doesn't need to be presentable.
Thoughts?
I like the readability part. I guess the con would be that we no longer will be "motivated" to update the issue with better descriptions?
I don't see that as a con. Usually the issue is described by all the comments, and going back and changing the original message feels very unnatural. Especially when the original comment was from a user.
This is a reasonable compromise as it still requires a good title for the issue.
On Wednesday, November 5, 2014, Andreas Öhlund [email protected] wrote:
I like the readability part. I guess the con would be that we no longer will be "motivated" to update the issue with better descriptions?
— Reply to this email directly or view it on GitHub https://github.com/Particular/GitHubReleaseNotes/issues/17#issuecomment-61734688 .
generally I approach it closing the original issue and opening a new one that links the original one. The original one has all the discussion and the triage, the new one is the one referenced in the release notes.
Most of the time the 2 stages have really different approaches, such has:
- Bug - when doing xyz the app crashes: the whole triage story goes on and discovers what the underlying issue is and opens a new issue;
- Bug - when the state is x and the user does y the component z fails;
To me the last one has a meaning in the release notes.
@mauroservienti That also seems silly to me. So now we have 2 issues, one with lots of discussion, but isn't in the milestone. The other issue is the one linked to in the release notes, but if you want to see the whole story you have to follow it back to the original issue.
I think we're missing the point of the release notes compiler. If we have to open separate issues just to write clean issues for the release notes, why not just manually write the release notes in the first place?
I'm not saying that we must do that all the times, I suppose that if you, or I or any Particular guy, open an issue you you know what you are doing. If the issue comes from the end user most of the times is something like: "My Saga does not work".
That's not an issue :-) is like my mother saying the printer does not print...so what? :-) That is the entry point of a triage story that maybe can open more than one issue, e.g. a bug in the saga finder and a document in the guidance repo that must be written.
In this sample the original issue raised from the user has no meaning, imho, in the release notes.
I think we're missing the point of the release notes compiler. If we have to open separate issues just to write clean issues for the release notes, why not just manually write the release notes in the first place?
Absolutely no, we do not need to open separate issues to have well looking issues in the release notes, but to correctly track what is going on.
@mauroservienti Alright. But my point in this issue still remains. Release notes are extremely verbose, and I'd like to have a solution that involves less work for us, and produces meaningful release notes that look nice and professional.
I'm +1 to go ahead since this change will make the issue titles more prominent we'll at least need to make sure that they are descriptive and correct
-1 For extra issues, I don't see the ROI given the noice it will create
On Wed, Nov 5, 2014 at 8:11 AM, Cameron MacFarland <[email protected]
wrote:
@mauroservienti https://github.com/mauroservienti Alright. But my point in this issue still remains. Release notes are extremely verbose, and I'd like to have a solution that involves less work for us, and produces meaningful release notes that look nice and professional.
— Reply to this email directly or view it on GitHub https://github.com/Particular/GitHubReleaseNotes/issues/17#issuecomment-61768111 .