Semantic-Release-Notes
Semantic-Release-Notes copied to clipboard
avanderhoorn
Severity instead of Priority?
priority - Noun:
- A thing that is regarded as more important than another.
- The fact or condition of being regarded or treated as more important.
I don't like the use of "priority" in the spec as priorities on issues can change over time.
I prefer severity as a way to label issues as this is less likely to change once it has been raised.
Secondly, the use of integers to represent priority is ok, but you lose the context to indicate what each value represents (and you might want more options like Showstopper for example).
So why not drop the need to do this:
1. This is a High priority list item.
1. This is a High priority list item.
2. This is a Normal priority list item.
And instead do this:
- (Showstopper) The house is on fire
- (High) The fire alarm is making noise
- (Medium) I can smell smoke
@nikmd23 has been talking about how ordering of priority in items is hard to read, and I like this as a compromise between readability and freedom of ordering.
Thoughts?
I'm a fan of this approach.
I think we should have 3-5 named tokens that we recognize, but support any values.
I'd also add one change to @shiftkey's example above:
- (Showstopper) The house is on fire
- (High) The fire alarm is making noise
- (Medium) I can smell smoke
- I am the default severity. No need for special syntax here.
- (Cosmetic) Installed a new oven in the kitchen.
Which demonstrates a "default" severity.
I agree with the above, I'm wondering though, if we should support the numbers as an option.
Having both does increase complexity (i.e. what happens if someone uses but the tag and the number), but if this could be worked through, it could make it easier for people that are happy with 1, 2 & 3 - High, Medium & Low.
In that, needing to type out (Showstopper), (High), etc is more than just typing the numbers and could be prone to typos. What is by convention, ordered lists translated to some of these default tags?
Meaning that the following:
1. This is a High priority list item.
1. This is a High priority list item.
2. This is a Normal priority list item.
Is the same as:
- (High) This is a High priority list item.
- (High) This is a High priority list item.
- (Medium) This is a Normal priority list item.
Also given our discussion about whether tokens like this need to be placed at the beginning or end of an item, should we support the following:
- This is a (High) priority list item.
- This is a (High) priority list item.
- This is a (Medium) priority list item.
- This is a (High) priority list item.
I'm not a fan of these contrived (in my words) samples. Because in the real world(tm) you wouldn't have "High" within the defect name, right? "High" is a label coming from some other source (bug tracking system etc) so you're probably not going to duplicate it in the message.
In that, needing to type out (Showstopper), (High), etc is more than just typing the numbers and could be prone to typos.
Not necessarily. Imagine a scenario where you're generating these documents from GitHub Issues - the tags you define there could become the category tags here.
Ultimately I see these categories are orthogonal to the messages themselves, and the benefits of free-form text (what if I have a category which is more important than "High"? how does I pass these categories to the formatter? etc) are greater than the risk of typos.
In addition, with the proposal to allow for any severity to be entered in between parenthesis, this would technically be valid:
- (1) This is a High priority list item.
- (1) This is a High priority list item.
- (2) This is a Normal priority list item.
However, I have realized that text labels do not, in and of themselves, contain an explicit ordering. We'd have no way of knowing that Showstopper > High > Crocodile.
We'd need a way to specify the ordering of the labels if a user deviated from the convention.
IE: srnParser.exe input.md -severity:"Showstopper, High, Crocodile"
Of course, -severity would default to a sensible set of well known severity values.
While I'm thinking about this, more and more I find Severity to be riddled with problems. (As well as Priority.)
- To be used in an aggregate fashion (like Glimpse would use across a set of plugins), everyone has to use the same set's of severity values and weights.
- Custom values need to be explained to users. A canonical set of values that everyone agrees to seems unlikely.
- Numbers are an unconstrained set, allowing users to put randomly high values like
17. Text values can be constrained, but see point No 2 above. - I'm wondering if this concept should be present in SRN at all. I'm thinking that an issue has a priority/severity, not a release note.
- It might be best to aim to not support this feature in SRN 1.0. We can always add it to SRN 1.1 as it would be a non-breaking change.
I know, I know, this is going to be a bit controversial. But can we outline the benefits of encoding this info into the release notes?
I know, I know, this is going to be a bit controversial. But can we outline the benefits of encoding this info into the release notes?
As I see it, release notes should represent a summary of what's changed in a given release. If I can see at a glance that's there's only been minor updates (without going to a secondary data source) then I can quickly evaluate if it's worth updating to this release.
That's why I like having the priority/severity value included. But I'm happy to drop this to keep this (categories is a good-enough alternative to provide this context) for 1.0.
I agree with you that is a benefit.
Perhaps this is a personal thing - but I've always looked at that axis as BugFix, Improvement & New Feature. I've never cared (as a software consumer) that a Showstopper bug was fixed.
Would severity only apply to bugs? Is there a (Low) new feature? Or a Showstopper Improvement?
Not arguing the case, just trying to tease out more details.
I've never cared (as a software consumer) that a Showstopper bug was fixed.
Fair. I guess it depends on the audience for reading these - are we talking about technical people or non-technical people or both?
Would severity only apply to bugs?
I believe so. For example, I separated out the release notes here into issues closed (which would have a severity) and pull requests (which may not be related to issues).
The way I see this is from a consumption perspective. Meaning, if we are parsing a five release that the user updated through, and in total there are 50 items addressed, if we want to summarise things for the user, how do we say "here are the top 6 things you should care about across these releases and you can click here so see the rest in order of which ones you should probably know about"
In this thought process I'm trying to address getting the user to absorb the most important information first and not drown them in info. Also I know that we can't get it 100% right, but it wold be nice if we could get it close. Maybe in the end we just have the rely on the dev ordering the issues in order of what a user should care about, and in the case I mention we loop through the releases round robin style picking an issues from each release as we go....
In this thought process I'm trying to address getting the user to absorb the most important information first and not drown them in info
Given that, I think that we should just encourage writers of SRN to order their items from highest to lowest.
I'd say move this to v1.1 and focus on the category tags for 1.0 as I can see myself using that much more.
Love the bump :D
It would have been nice to have this sorted but I can see that's its might be more complex then it seems on the surface.
My only hesitation with not including it from the get go is that one of SRN value props is that depending on the rendering engine, it can intelegently select the most import issues from a release.
I'm worried that if we don't have this, we loose a chunk of value.
On Saturday, April 6, 2013, Brendan Forster wrote:
I'd say move this to v1.1 and focus on the category tags for 1.0 as I can see myself using that much more.
— Reply to this email directly or view it on GitHubhttps://github.com/Glimpse/Semantic-Release-Notes/issues/6#issuecomment-15984128 .
Perhaps it's time to implement a demo renderer to demonstrate what the end user sees (and benefits from) when consuming SRN notes.
True dat.
I second that idea - or at least a mockup of it.
On Apr 5, 2013, at 6:58 PM, Brendan Forster [email protected] wrote:
Perhaps it's time to implement a demo renderer to demonstrate what the end user sees (and benefits from) when consuming SRN notes.
— Reply to this email directly or view it on GitHub.
I think that if we make a bit more of a demo and things are looking good, we can use the glimpse version stuff as a production/real test case.
On Saturday, April 6, 2013, Nik Molnar wrote:
True dat.
I second that idea - or at least a mockup of it.
On Apr 5, 2013, at 6:58 PM, Brendan Forster <[email protected]<javascript:_e({}, 'cvml', '[email protected]');>> wrote:
Perhaps it's time to implement a demo renderer to demonstrate what the end user sees (and benefits from) when consuming SRN notes.
— Reply to this email directly or view it on GitHub.
— Reply to this email directly or view it on GitHubhttps://github.com/Glimpse/Semantic-Release-Notes/issues/6#issuecomment-15986538 .
And this would likely help shake out the value in priority/severity labels