GHC boot-library package changelogs & release-notes
Hello fellow GHC devs, As some of you might have noticed, I added a changelog.md file to libraries/base: https://github.com/ghc/packages-base/blob/c8634027d4e3315a2276fb1be8168c4864... (please feel free to fix any typos/omissions/whatever you notice) My hope/motivation is that since Hackage gained the ability to display changelog files, the rather extensive changes in `base` might be a bit more easily/conveniently accessible on Hackage. I chose to use Markdown format, as I believe it may be more convenient to maintain/edit the `base` changelog as plain text rather than having to edit XML after each noteworthy change in `base`. And as the release-notes typically only exploit a subset of the Docbook facilities, the conversion to Docbook XML could be performed semi-automatically shortly before a release. Moreover, the release notes from previous major GHC release (which in the past contained the major changes in `base` et al.) are usually removed again. While a separate changelog file would usually retain (more) version history. Therefore, I'd propose to switch from editing the user's guide release note for library release notes to using Hackage-changelog files in Markdown format (following a common structural convention) and make it the release-manager's responsibility to integrate the respective package's changelog content into the user's guide. Any comments? Cheers, hvr
Hi Herbert, So who should add to the changelog? If I'm committing a new feature to the base library, should my commit include a small addition to the changelog describing my change? Good idea btw! :) Best, Arash On 2014-01-29 17:32, Herbert Valerio Riedel wrote:
Hello fellow GHC devs,
As some of you might have noticed, I added a changelog.md file to libraries/base:
https://github.com/ghc/packages-base/blob/c8634027d4e3315a2276fb1be8168c4864...
(please feel free to fix any typos/omissions/whatever you notice)
My hope/motivation is that since Hackage gained the ability to display changelog files, the rather extensive changes in `base` might be a bit more easily/conveniently accessible on Hackage.
I chose to use Markdown format, as I believe it may be more convenient to maintain/edit the `base` changelog as plain text rather than having to edit XML after each noteworthy change in `base`. And as the release-notes typically only exploit a subset of the Docbook facilities, the conversion to Docbook XML could be performed semi-automatically shortly before a release.
Moreover, the release notes from previous major GHC release (which in the past contained the major changes in `base` et al.) are usually removed again. While a separate changelog file would usually retain (more) version history.
Therefore, I'd propose to switch from editing the user's guide release note for library release notes to using Hackage-changelog files in Markdown format (following a common structural convention) and make it the release-manager's responsibility to integrate the respective package's changelog content into the user's guide.
Any comments?
Cheers, hvr _______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
Hello Arash, On 2014-01-29 at 18:21:05 +0100, Arash Rouhani wrote:
So who should add to the changelog? If I'm committing a new feature to the base library, should my commit include a small addition to the changelog describing my change?
If you deem your modification release-note-worthy, then yes. The idea is to keep the code-change and the changelog modification more localized to each other. With the current scheme, you have to make two commits, as the the release-notes file is usually in a different repository. Cheers, hvr
Herbert Would you like to add some notes to https://ghc.haskell.org/trac/ghc/wiki/Commentary/Libraries, to describe what the file is, and the criteria for modifying it? (After all, the patch history is a kind of change log too.) Thanks Simon | -----Original Message----- | From: ghc-devs [mailto:ghc-devs-bounces@haskell.org] On Behalf Of | Herbert Valerio Riedel | Sent: 29 January 2014 16:33 | To: ghc-devs | Subject: GHC boot-library package changelogs & release-notes | | Hello fellow GHC devs, | | As some of you might have noticed, I added a changelog.md file to | libraries/base: | | https://github.com/ghc/packages- | base/blob/c8634027d4e3315a2276fb1be8168c486419785a/changelog.md | | (please feel free to fix any typos/omissions/whatever you notice) | | My hope/motivation is that since Hackage gained the ability to display | changelog files, the rather extensive changes in `base` might be a bit | more easily/conveniently accessible on Hackage. | | I chose to use Markdown format, as I believe it may be more convenient | to maintain/edit the `base` changelog as plain text rather than having | to edit XML after each noteworthy change in `base`. And as the | release-notes typically only exploit a subset of the Docbook | facilities, | the conversion to Docbook XML could be performed semi-automatically | shortly before a release. | | Moreover, the release notes from previous major GHC release (which in | the past contained the major changes in `base` et al.) are usually | removed again. While a separate changelog file would usually retain | (more) version history. | | Therefore, I'd propose to switch from editing the user's guide release | note for library release notes to using Hackage-changelog files in | Markdown format (following a common structural convention) and make it | the release-manager's responsibility to integrate the respective | package's changelog content into the user's guide. | | Any comments? | | Cheers, | hvr | _______________________________________________ | ghc-devs mailing list | ghc-devs@haskell.org | http://www.haskell.org/mailman/listinfo/ghc-devs
participants (4)
-
Arash Rouhani -
Herbert Valerio Riedel -
Herbert Valerio Riedel -
Simon Peyton Jones