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 [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//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?

[AnneTheAgile]

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

[laedit]

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?

[avanderhoorn]

Are you thinking that this would be part of the file name or the header within the release note?

[laedit]

The header within the release note.
I think it is too much info for a file name.

[avanderhoorn]

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.

[laedit]

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.

[avanderhoorn]

Does anyone else have any thoughts on these before moving ahead?

[AnneTheAgile]

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?

[avanderhoorn]

I like year month day as well. Seems to avoid any possible confusion no matter were you are from.

[JakeGinnivan]

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

[avanderhoorn]

Makes sense.

[AnneTheAgile]

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.

[laedit]

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.

[avanderhoorn]

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

[JakeGinnivan]

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

[avanderhoorn]

Ok, now that we have come with the date format we need to settle on what determines the Header for the release notes, if that header facilitates multiple releases in the same blob of text/document, etc.

Denoting the release/document title
As discussed above, using # for this purpose probably makes the most sense:

• Are we ok with shifting the current usage of # from denoting Category titles to release/document titles?
• As a side effect of the above, are we ok with shifting Category titles to ##?

Multiple releases per document/text blob
Having multiple releases in the one document/text blob has been discussed for a while:

• Are we happy that with changing things so that # denotes the release/document title, that this will be the mechanism by which we allow allow for multiple releases in the one document/text blob?

Exact format for the title
One thing that we haven't really discussed in the structure of the title. Like always I think that it flexible (to a point), intuitive and easy to get it right.

Given that, here are some early thoughts:

// Case 1 - Version
# 1.2.3-beta1
...

//    Parsed result - { version: '1.2.3-beta1' }


// Case 2 - Version and Release Date
# 1.2.3-beta1 2015-02-15
...

//    Parsed result - { version: '1.2.3-beta1', date: '2015-02-15' }


// Case 3 - Release Date
# 2015-02-15
...

//    Parsed result - { date: '2015-02-15' }


// Case 4 - Title
# Snow Leopard 
...

//    Parsed result - { title: 'Snow Leopard' }


// Case 5 - Title, Version and Release Date
# Snow Leopard 1.2.3-beta1 2015-02-15
...

//    Parsed result - { version: '1.2.3-beta1', date: '2015-02-15', title: 'Snow Leopard'  }


// Case 6 - Title, Version and Release Date
# Snow Leopard 2015-02-15 1.2.3-beta1
...

//    Parsed result - { version: '1.2.3-beta1', date: '2015-02-15', title: 'Snow Leopard'  }


// Case 7 - Title, Version and Release Date with special characters
# Snow Leopard: 1.2.3-beta1 - 2015-02-15
...

//    Parsed result - { version: '1.2.3-beta1', date: '2015-02-15', title: 'Snow Leopard'  }

I'm thinking that for sanity's sake if we needed to show more than Title, Version and Release Date, this would need to shift to keyed metadata - as discussed here #14. Additionally, I'm already wondering if a simple enough parser can be created for parsing the above use cases. What do you think, are there many more use cases, etc?

For all the above, does this feel right to others, keep moving forward with these change?

[JakeGinnivan]

Finally I have a chance to open my laptop and read this stuff properly.

One problem I have is that markdown is itself a format which can be rendered directly. I think that any sort of header should be a version title, this allows the use of #, ## or ### for a release title. Having H1 is actually a bit much for the document when viewed directly in GitHub. Then I like the idea of sections changing to **section**.

As for the title itself I think those cases are good but we need to think about error cases:

## Snow Leopard: 1.2.3-beta1 - 2015-02-15 Foo - Error: Ambiguous Title, could be 'Foo' or 'Snow Leopard'

What other cases would blow up?

[AnneTheAgile]

" Multiple releases per document/text blob"
What is the idea with this? Are we talking about having the long Changelog of all versions for all time living in such a blob? It seems like there should be a nice way to consider teach release separately and together.

[laedit]

@JakeGinnivan It's a good idea to have a different syntax to distinguish a release title from a section.
But I'm not comfortable with having several ways to indicated a release title: I don't think it's the purpose of the semantic release notes to be used directly, like showed in the website the data are parsed and formatted.
So we can use the # for the release title and then use another like ### when formatting for use on GitHub?

[JakeGinnivan]

I am saying all headers are considered release titles. Maybe except h4. That is not multiple ways, but it allows flexibility.

Why have the format in markdown if it will never be rendered? :)

Sent from my Windows Phone

---

From: Jérémie Bertrandmailto:[email protected]
Sent: ý02/ý03/ý2015 10:57
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)

@JakeGinnivanhttps://github.com/JakeGinnivan It's a good idea to have a different syntax to distinguish a release title from a section.
But I'm not comfortable with having several ways to indicated a release title: I don't think it's the purpose of the semantic release notes to be used directly, like showed in the website the data are parsed and formatted.
So we can use the # for the release title and then use another like ### when formatting for use on GitHub?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/11#issuecomment-76737755.

[JakeGinnivan]

I like having a single releasenotes.md in my GitHub repo.

Sent from my Windows Phone

---

From: AnneTheAgilemailto:[email protected]
Sent: ý01/ý03/ý2015 00:43
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)

Multiple releases per document/text blob
What is the idea with this? Are we talking about having the long Changelog of all versions for all time living in such a blob? It seems like there should be a nice way to consider teach release separately and together.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/11#issuecomment-76575956.

[laedit]

All right, you mark a point :)

[avanderhoorn]

@AnneTheAgile That was the idea. Like @JakeGinnivan said, many people like having a single document with a running list of release notes. Hence making sure the format supports having n number of releases in one "doc" seems to make sense.

I like the idea of switching it over to **section** that's on its own line. Part of me thinks that when you are reading a document, it doesn't stand out as much as a sub section title, but this could just be me.

[JakeGinnivan]

Maybe one a title is matched any lesser header is a section?

As an example:

# title
## section
- issue

Also valid

## title
### section
- issue

Also

### title
#### section
- issue

Also

### title
**section**
- issue

This could be more complex but makes for nice reading in raw format or rendered markdown. All are semantically the same (lesser header is a section)

Sent from my Windows Phone

---

From: Anthony van der Hoornmailto:[email protected]
Sent: ý02/ý03/ý2015 11:13
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)

@AnneTheAgilehttps://github.com/AnneTheAgile That was the idea. Like @JakeGinnivanhttps://github.com/JakeGinnivan said, many people like having a single document with a running list of release notes. Hence making sure the format supports having n number of releases in one "doc" seems to make sense.

I like the idea of switching it over to section that's on its own line. Part of me thinks that when you are reading a document, it doesn't stand out as much as a sub section title, but this could just be me.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/11#issuecomment-76741122.

[avanderhoorn]

My only concern is if someone uses the headings with the intent of them to be ### title and #### section, and then has other # xyz and ## abc's in the document, how would that work? If headings are present in the document, would we always interpret the first 2 headings as Title and Section, regardless of if they are # & ## or ### & ####? Seems a bit loose, but I can see why.

[JakeGinnivan]

I think we should enforce that they are all the same. So if you use #, ## and ### in the same document it will fail. It is loose but still semantically the same.

[JakeGinnivan]

Just reviving this discussion. Thoughts on the above point?

I still think that being a markdown format, it should be able to be rendered as is and not have to transform markdown -> markdown to be formatted nicely.

[laedit]

I'm ok with the flexibility, like you said it is a markdown format and should be able to rendered as is.
But we must not forget that in the goals of the format there is the support of other format so we must have rules that able the format to be parsed and rendered as other format (or markdown if we want to format it differently 😃).

So to resume:

• #, ## or ### are used to indicate a release title
• section is indicated with either ** or # with one more of those used for the release title if it's part of a release (multiple releases in the same document)
• the chars used must be constant through all the document

Is that ok?

[JakeGinnivan]

Yep, that works for me. @avanderhoorn?

[JakeGinnivan]

Just thought of an issue with my suggestion, how would we be able to distinguish between a document with multiple releases and no sections vs a document with just multiple sections?

[JakeGinnivan]

@avanderhoorn: 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 going back to this is a better idea. Section headers are simply a bold line, and #, ## and ### all denote a release title.

[avanderhoorn]

Just and update so you know that I'm not ignoring you guys, I've just had a baby and on leave at the moment. Back on deck next week.

[laedit]

@avanderhoorn Congrats! 😃

@JakeGinnivan Nice catch I haven't see that. I'm ok with the bold line for a section, just to clarify are we supporting the two markdown notations (** and __)?

[JakeGinnivan]

@avanderhoorn Congrats! All good enjoy your leave.

@laedit yeah we should support both

[JakeGinnivan]

Allowing multiple header sizes though would mean that metadata would need to be held in the json representation to allow round-trips.

## Title
Summary

**Section
 - Blah
 - Blah2

**Another section**

Turns into

{
    "title": "Title",
    "summary" : "Summary",
    "sections" : [ {
        "items" : [ {
            "summary" : "Blah"
            }, {
            "summary" : "Blah2"
            }]
        }],
    "metaData" : {
        "titleLevel": 2
    }
}

[avanderhoorn]

So what would multiple releases look like?

## Title 1
Summary

**Section 1a
 - Blah
 - Blah2

**Another section 1b**

## Title 2
Summary

**Section 2a
 - Blah
 - Blah2

**Another section 2b**

Also are we agreeing to fail a document that has the presence of multiple heading types or would we say that what ever the lowest heading type that is present is the release one?

[JakeGinnivan]

Unsure what you mean by would we say that what ever the lowest heading type that is present is the release one.

I am leaning towards only one size of headers present in the document

[avanderhoorn]

I was thinking something like:

# Document Title
...

## Release 1
...

## Release 2
....

In this case it would see that multiple heading levels are used and ignore the "#" in favour for the lowest heading level (in this case "##").

I personally don't like this... I don't think its 100% clear.

[JakeGinnivan]

Ah I get you.. Hrrm.

For my scenarios I can't see the need for having a document title inside the release notes. If you publish via jekyll or something the title will come from yaml front-matter and for ReleaseNotes.md the title is inferred from the filename.

I vote for a single header size within a document.

[laedit]

Good for me too, otherwise it's too confusing.

[avanderhoorn]

Great!