Semantic-Release-Notes
Semantic-Release-Notes copied to clipboard
avanderhoorn
Provide a way to assign a date to each release
As the title says, I think there should be a way to tag a release with an (optional) release-date.
Yep, I think this could be a good addition. I just wonder how much of this extra supporting metadata should be a part of the spec, without risking downing out the core intent. But maybe its up to the author to decide what they want to pay attention too and provide... Thought?
On Mon, Apr 22, 2013 at 6:44 PM, Dennis Daume [email protected]:
As the title says, I think there should be a way to tag a release with an (optional) release-date.
— Reply to this email directly or view it on GitHubhttps://github.com/Glimpse/Semantic-Release-Notes/issues/11 .
Since it's quite common (well, at least I think it is) to write the date of the release beside the version, I'd say this should be supported directly by the spec, so that nobody has to bake their own solution every time. But it should also definitely be optional.
This could also fit with @shiftkey 's idea in #2 to use the file's name as version, for example:
docs/releases/YYYY-MM-DD A.B.C.md or docs/releases/A.B.C YYY-MM-DD.md
and when not using the date, just
docs/releases/A.B.C.md
I'm skeptical on the need for this because other systems will take care of tracking this release date for me.
For example:
- RubyGems - http://rubygems.org/gems/jekyll/versions
- NuGet - http://nuget.org/packages/Mahapps.Metro/
As a consumer or publisher of software, the date of a release isn't something I really care about (i'm excluding blog posts from this discussion).
Some scenarios:
- periodic releases of software (end of iteration etc) - the same day of the week (assuming no slippage of course) and the calendar just moves slightly
- hotfix releases - the minor version number is incremented and I get an email to go download it immediately
- continuous integration builds - whenever the source was updated and passes all tests, I get it off NuGet or whatever
@flagbug can you share some scenarios about how controlling this date (rather than leaving it up to external factors) is of benefit to you?
I'm also on the fence whether this is needed or not, but I think we get something very close as a happenstance if we take on @shiftkey's suggestion in #2.
If we do take on #2, and we support/recognize file names that follow Semantic Versioning (semver), than we should make pre-release version and the build version available in the returned structured output.
Here's some examples:
+----------------------------------+---------+---------+------------+------------+
| Filename | Name | Version | PreRelease | Build |
|----------------------------------|---------|---------|------------|------------|
| Product.md | Product | $null | $null | $null |
| Product.2.1.1.md | Product | 2.1.1 | $null | $null |
| Product.2.1.1-beta.md | Product | 2.1.1 | beta | $null |
| Product.2.1.1+2013-04-23.md | Product | 2.1.1 | $null | 2013-04-23 |
| Product.2.1.1-beta+2013-04-23.md | Product | 2.1.1 | beta | 2013-04-23 |
+----------------------------------+---------+---------+------------+------------+
Many .NET developers don't realize that the semver specification provides for adding a build token after the + because NuGet does not currently support that part of the spec.
Developers already use the build token to place the date of a given build (so this usage isn't out of line) or the hash of last commit.
Of course, given that the build token can be any character in the set [0-9A-Za-z-], we wouldn't be able to assume that the build token is a date, or even parse it - but the string representation would in fact be available.
At the same time, I also argue that a build label isn't relevant for end users/release notes, but if we are going to support semver in the file name, we should support the whole spec.
One last comment, but it isn't one I'm particularly concerned about:
Supporting all of semver in a file name means that a user can and will place a + character in their file names. The + character is supported by all file systems, but not in SharePoint.
Like I said, I don't really care about this limitation, but wanted to point it out.
@nikmd23 i'm on board with enhancing #2 to indicate that build and pre-release tags are supported. That matrix is an excellent overview of the options available.
The + character is supported by all file systems, but not in SharePoint.
Who can/should we complain to about that? (serious question)
@shiftkey I have no clue who to complain to about SharePoint, but I know that limitation had been around for at least the last three major versions - so I'm not sure that it would be changeable anyways.
I do not, and I think that the collective we do not either.
However, you asked:
Who can/should we complain to about that? (serious question)
So I provided the serious answer. :stuck_out_tongue_winking_eye:
My only slight concern with the build number idea is that to include a date we are saying that:
- you need to have one "file" per release
- the build number is going to be a date
@avanderhoorn Isn't the idea that you can write anything in the range of [0-9A-Za-z-] behind the build token and then everyone can parse what they write behind the + for themselves?
Agreed. My concern was around if someone isn't using date as their build number and want to keep what ever system the have, but want to have a date.
On Wednesday, April 24, 2013, Dennis Daume wrote:
@avanderhoorn https://github.com/avanderhoorn Isn't the idea that you can write anything in the range of [0-9A-Za-z-] behind the build token and then everyone can parse what they write behind the + for themselves?
— Reply to this email directly or view it on GitHubhttps://github.com/Glimpse/Semantic-Release-Notes/issues/11#issuecomment-16918618 .
I would like this too, in the case of multiple releases in a singe document.
The releases stuff would be good to get specd out. I think possibly releases should be in the format
# 0.0.0 (date)
The date in brackets would be optional
On a slight tangent. How does this differentiate between a release with sections, or multiple releases in a single document?
+1 having the ability and strong recommendation to include date. My reasoning is for sanity checks. If I go to a release page, it should be obvious by inspection how new it is (-not- in the horrid offset format date) and also how far apart the releases are spaced.
It also helps me error-check my download/install.
I think that a release in a multiple release document could be recognize by this format:
# [v]0.0.0 [date] [summary]
The 'v', date and summary are optionals and the version (0.0.0) must respect the SemVer format.
Are you ok with that?
Are you thinking that this would be part of the file name or the header within the release note?
The header within the release note. I think it is too much info for a file name.
Makes sense to me - anyone got any other objections/thoughts? Only thing to be worked out is what a header for the release would look like. Currently the # is "known" as a category. Maybe this should change so that # is the release title and **xyz** on a line of its own is a section header... Solving this issue would also better allow for multiple release within the one document - which we have talked about but don't currently support.
I think **xyz** or ## xyz could do the trick.
If a document has both #and ## it's a multi-release document, otherwise it's considered as a one release document.
Sounds great to me. I like date in ISO format, eg 2015-01-31, and due to a situation I had a few days ago I'm wondering if datestamp would also be reasonable to include? Or maybe is the timestamp already available elsewhere and it can be posted in the description?
I like year month day as well. Seems to avoid any possible confusion no matter were you are from.
For release notes I think 'dd mmm yy' works well. Eg '26 Feb 15' which is also universal.
Sent from my Windows Phone
From: Anthony van der Hoornmailto:[email protected] Sent: ý26/ý02/ý2015 12:26 To: Glimpse/Semantic-Release-Notesmailto:[email protected] Cc: Jake Ginnivanmailto:[email protected] Subject: Re: [Semantic-Release-Notes] Provide a way to assign a date to each release (#11)
I like year month day as well. Seems to avoid any possible confusion no matter were you are from.
— Reply to this email directly or view it on GitHubhttps://github.com/Glimpse/Semantic-Release-Notes/issues/11#issuecomment-76223120.
To me the cool thing about year-month-day is its being inherently directly sortable, no conversion needed, plus of course no European/American mixups are possible.
I think the 'dd mmm yy' format could bring some problem, unless we suppose the language used is english. So i'm more in favor of 'year-month-day', but we could still use the 'dd mmm yy' as default format for the HTML output.
+1 I think the output format can be what ever the author of the formatter wants it to be be, but the SRN format should be more controlled and standardised - hence I'm leaning toward yyyy-mm-dd.
Sounds fair and supports non-english release notes.
Sent from my Windows Phone
From: Anthony van der Hoornmailto:[email protected] Sent: ý27/ý02/ý2015 00:18 To: Glimpse/Semantic-Release-Notesmailto:[email protected] Cc: Jake Ginnivanmailto:[email protected] Subject: Re: [Semantic-Release-Notes] Provide a way to assign a date to each release (#11)
+1 I think the output format can be what ever the author of the formatter wants it to be be, but the SRN format should be more controlled and standardised - hence I'm leaning toward yyyy-mm-dd.
— Reply to this email directly or view it on GitHubhttps://github.com/Glimpse/Semantic-Release-Notes/issues/11#issuecomment-76336478.