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?
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’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?
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:
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.)
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.)
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!
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.)