Provide a way to assign a date to each release

[flagbug]

As the title says, I think there should be a way to tag a release with an (optional) release-date.

[avanderhoorn]

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 notifications@github.comwrote:

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//issues/11
.

[flagbug]

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

[shiftkey]

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?

[nikmd23]

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.

[nikmd23]

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.

[shiftkey]

@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)

[flagbug]

@nikmd23 I think this is an excellent idea!

[nikmd23]

@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.

[shiftkey]

@nikmd23 we don't actually care about the Sharepoint filesystem, right?

[nikmd23]

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. 😜

[avanderhoorn]

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

[flagbug]

@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?

[avanderhoorn]

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//issues/11#issuecomment-16918618
.

[JakeGinnivan]

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

[JakeGinnivan]

On a slight tangent. How does this differentiate between a release with sections, or multiple releases in a single document?