Bug#722997: File currently included as changelog is (at most) a NEWS file

[Jonas Smedegaard]

Quoting Alessandro Ghedini (2014-07-12 12:28:15)
> On Sat, Jul 12, 2014 at 12:24:11AM +0200, Jonas Smedegaard wrote:
>> Thanks for including upstream release notes.  That file, however, 
>> seems at most a NEWS file: It is apparently an unmaintained broad 
>> overview of changes for some specific release - without mention of 
>> which one, but didn't at all since it was included and mentions only 
>> two git hashes, no version numbers.
>
> The RELEASE_NOTES file *is* maintained (in fact *I* maintain it, since 
> I somehow became mpv's release manager) and it refers to the latest 
> major release (0.X.0).

Ohh, well congratulations with your title, then - and the burden that 
comes with it, like being "pestered" with bugreports like this ;-)


> It's also not really "broad", since it reflects pretty accurately what 
> user-facing changes went into the release (of course, I could have 
> missed something since the 0.4.0 release had something like 1400 new 
> commits).
>
> But I can see why it's confusing. I guess I can add the version number 
> at the top or something, that's not a problem.

Makes perfect sense for a NEWS file to include only major changes (which 
in effect means only changes applied to major releases when release 
management is strict about not sneaking in major changes in minro 
releases).

So please ignore my too harsh judgement on that file - only thing 
confusing is shipping it as "changelog": A changelog is expected to 
_cover_ all changes even if not necessarily very granularly - i.e. 
shortening to say "Misc. internal code cleanup" is fine, but making a 
release with *no* changelog entry is.... weird.


> The notes however do not include changes in the point releases (e.g. 
> 0.4.1), which are only fixes for regressions introduced by previous 
> releases in the same 0.X branch. Not sure if it would make sense to 
> include them as well (or how). In the future there won't be as many 
> point releases as in the past tough (which is a good thing I guess), 
> since major releases will be released more often, so maybe this isn't 
> that much of a problem.
>
> I've also thought about having a proper ChangeLog file that includes 
> all the releases, but it would be difficiult to maintain due to mpv's 
> release process (releases come from separate release/0.X branches, 
> which are never merged back into master, so at best the chanelog would 
> only include releases from the same 0.X series).
>
> I'm still getting the hang of this release manager business tough 
> (v0.4.0 was my first release, snd it was a pretty big one), so 
> suggestions are appreciated.

Ideally a changelog is proofread and tidied similar to a NEWS file, not 
just blindly spewed from commit messages. E.g. things added but then 
reverted again within same release, and an entry "changed foo to bar" 
and then another "changed bar to baz" would be merged to "changed foo to 
baz".  When I suggested to use git2cl it was to do the least complex: A 
noisy untidied changelog is better than none!

NB! All what I write is just opinion - I am no expert in this, just have 
read a gazilion NEW and changelog files over time, and noticed some 
patterns.  No doubt you can find stronger documents on documentation 
(e.g. the GNU project is a good place to look if you like working by 
solid principles).

When you are involved upstream, you might benefit from 
git-merge-changelog (but honestly I have no clue how exactly, just 
stumbled upon it while looking for git2cl).


 - Jonas

-- 
 * Jonas Smedegaard - idealist & Internet-arkitekt
 * Tlf.: +45 40843136  Website: http://dr.jones.dk/

 [x] quote me freely  [ ] ask before reusing  [ ] keep private
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 949 bytes
Desc: signature
URL: <http://lists.alioth.debian.org/pipermail/pkg-multimedia-maintainers/attachments/20140712/72b68780/attachment.sig>