1

We have this document, which captures some of the evolution of swift over time in the form of release notes:
https://github.com/apple/swift/blob/master/utils/buildbot-release-notes.txt

We’ve started updating it for behavior changes in Swift 2.2, and think that something like it is important so that when we do a release, we have a way to make sure that sometime important isn’t missed. Users like to know what’s new :-)

That said, it has two pretty serious problems:
- It is missing content on what happened between Oct 2014 and the start of the Swift 2.2 cycle.
- It is a weird little text file off in an undiscoverable place in the source tree.

Fixing the former problem is a bit of an archeology exercise, the later problem is more of a content/design problem. Is anyone interested in tackling either of these?

-Chris

1 Like
2

I'd be willing to tackle the second problem (the content/design). I saw someone tweet about this file the other day, and it took me a while to find it in the utils directory. It was a great read, but also kind of a pain as one long doc because I preferred to read from the oldest notes to the most recent. I was thinking it might make sense to split it out into separate files based on the release dates, and move them into a subdirectory of the docs directory. For example:

docs/release-notes/2014-10-09-release-notes.md

Or something similar. Thoughts?

-joe

···

On Dec 5, 2015, at 12:54 PM, Chris Lattner <clattner@apple.com> wrote:

We have this document, which captures some of the evolution of swift over time in the form of release notes:
https://github.com/apple/swift/blob/master/utils/buildbot-release-notes.txt

We’ve started updating it for behavior changes in Swift 2.2, and think that something like it is important so that when we do a release, we have a way to make sure that sometime important isn’t missed. Users like to know what’s new :-)

That said, it has two pretty serious problems:
- It is missing content on what happened between Oct 2014 and the start of the Swift 2.2 cycle.
- It is a weird little text file off in an undiscoverable place in the source tree.

Fixing the former problem is a bit of an archeology exercise, the later problem is more of a content/design problem. Is anyone interested in tackling either of these?

-Chris

_______________________________________________
swift-dev mailing list
swift-dev@swift.org
https://lists.swift.org/mailman/listinfo/swift-dev

3

It was a great read, but also kind of a pain as one long doc because I preferred to read from the oldest notes to the most recent.

I find it useful to have change notes in a single document – it’s easy to search and find when a feature was introduced.

I was thinking it might make sense to split it out into separate files based on the release dates, and move them into a subdirectory of the docs directory. For example:

docs/release-notes/2014-10-09-release-notes.md

Splitting them into multiple files is fine, but please have *something* that renders them as a single continuous page – substantially easier to search, and save you opening a stack of files if you want to read through multiple change sets at once.

Personally I’d just tidy up the existing doc and put it in at the top-level of the repo as something like CHANGELOG or CHANGES.md. (A Markdown file extension would also make it a bit prettier on GitHub.)

— Alex

···

On 5 Dec 2015, at 20:54, joe via swift-dev <swift-dev@swift.org> wrote:

4

Ok, that makes sense. I can start by moving it to the root as a single markdown doc and making sure it renders well on GitHub. Any strong feelings on CHANGES.md vs CHANGELOG.md?

···

On Dec 5, 2015, at 3:00 PM, Alex Chan <alex@alexwlchan.net> wrote:

On 5 Dec 2015, at 20:54, joe via swift-dev <swift-dev@swift.org> wrote:

It was a great read, but also kind of a pain as one long doc because I preferred to read from the oldest notes to the most recent.

I find it useful to have change notes in a single document – it’s easy to search and find when a feature was introduced.

I was thinking it might make sense to split it out into separate files based on the release dates, and move them into a subdirectory of the docs directory. For example:

docs/release-notes/2014-10-09-release-notes.md

Splitting them into multiple files is fine, but please have *something* that renders them as a single continuous page – substantially easier to search, and save you opening a stack of files if you want to read through multiple change sets at once.

Personally I’d just tidy up the existing doc and put it in at the top-level of the repo as something like CHANGELOG or CHANGES.md. (A Markdown file extension would also make it a bit prettier on GitHub.)

— Alex

5

Ok, that makes sense. I can start by moving it to the root as a single markdown doc and making sure it renders well on GitHub. Any strong feelings on CHANGES.md vs CHANGELOG.md?

CHANGELOG.md sounds fine to me, thank you for doing this Joe!

-Chris

···

On Dec 5, 2015, at 1:06 PM, joe <joe@polka.cat> wrote:

On Dec 5, 2015, at 3:00 PM, Alex Chan <alex@alexwlchan.net> wrote:

On 5 Dec 2015, at 20:54, joe via swift-dev <swift-dev@swift.org> wrote:

It was a great read, but also kind of a pain as one long doc because I preferred to read from the oldest notes to the most recent.

I find it useful to have change notes in a single document – it’s easy to search and find when a feature was introduced.

I was thinking it might make sense to split it out into separate files based on the release dates, and move them into a subdirectory of the docs directory. For example:

docs/release-notes/2014-10-09-release-notes.md

Splitting them into multiple files is fine, but please have *something* that renders them as a single continuous page – substantially easier to search, and save you opening a stack of files if you want to read through multiple change sets at once.

Personally I’d just tidy up the existing doc and put it in at the top-level of the repo as something like CHANGELOG or CHANGES.md. (A Markdown file extension would also make it a bit prettier on GitHub.)

— Alex

6

No problem at all. Thanks for adding back the older missing stuff. I didn't even realize that was added back until I was editing the formatting and didn't recognize some of it from when I read it the other day.

···

On Dec 5, 2015, at 11:16 PM, Chris Lattner <clattner@apple.com> wrote:

On Dec 5, 2015, at 1:06 PM, joe <joe@polka.cat> wrote:

Ok, that makes sense. I can start by moving it to the root as a single markdown doc and making sure it renders well on GitHub. Any strong feelings on CHANGES.md vs CHANGELOG.md?

CHANGELOG.md sounds fine to me, thank you for doing this Joe!

https://github.com/apple/swift/blob/master/CHANGELOG.md

-Chris

On Dec 5, 2015, at 3:00 PM, Alex Chan <alex@alexwlchan.net> wrote:

On 5 Dec 2015, at 20:54, joe via swift-dev <swift-dev@swift.org> wrote:

It was a great read, but also kind of a pain as one long doc because I preferred to read from the oldest notes to the most recent.

I find it useful to have change notes in a single document – it’s easy to search and find when a feature was introduced.

I was thinking it might make sense to split it out into separate files based on the release dates, and move them into a subdirectory of the docs directory. For example:

docs/release-notes/2014-10-09-release-notes.md

Splitting them into multiple files is fine, but please have *something* that renders them as a single continuous page – substantially easier to search, and save you opening a stack of files if you want to read through multiple change sets at once.

Personally I’d just tidy up the existing doc and put it in at the top-level of the repo as something like CHANGELOG or CHANGES.md. (A Markdown file extension would also make it a bit prettier on GitHub.)

— Alex