[Geany-devel] Geany-Plugins & ChangeLogs

[Lex Trotman]

>
> BTW, perhaps we should then see how everybody sees these different (or
> not) things that are NEWS, ChangeLog and VCS history.
>

There are lots of ways to use these files, none is *right* but you
need to have a standard :-)

I think that the thread to date has suggested most of the ways they
are used, to summarise:

1. The ChangeLog is for non-VCS situations like tarballs.  So it
should match the VCS commit logs.  Generating it automatically or not
depends on the process you use to generate the non-VCS situation.  If
its generated manually (the current Geany process) then keeping it in
VCS is good since it maintains the connection between the two.

2. The VCS commit message is to document *why* the commit is made,
*what* is changed is recorded by the VCS (much better than we can).
Rules on what should be committed are project specific and usually
differ depending on if the commit is being made to the trunk, a branch
or the developers local private copy where he can commit "This is as
far as I got before I went to bed" :-).

3. Changelog and VCS are developer tools, NEWS or Release Notes are
user oriented documentation about a release, not every commit.

Release Notes should have *all* changes in user terms, the user should
not have to read ChangeLog or VCS to find out what changed in the
release since they don't care about what files and functions changed.
It should also contain user info such as "this is not backward
compatible, you need to change ..." and alternatives to deprecations,
stuff not usually included in ChangeLog/VCS commit message.

NEWS IMO should be a summary of major points of the Release notes (eg
compatibility breaks) and can also contain non-software related
information such as project personnel changes, new websites or
whatever and may even contain some future directions.

News and Release Notes probably can't be fully autogenerated from the
VCS/ChangeLog, although it can be a start for the Release Notes so no
change is forgotten.

Cheers
Lex