Re: Changelog formatting and project rules

[Murray Cumming <murrayc murrayc com>]

On Tue, 2007-05-29 at 11:37 +0200, Philip Van Hoof wrote:
> Although I allow the typical ChangeLog formatting where you put the
> filenames that you changed in front of your changes, I am not requiring
> it.
> 
> The reasons are quite simple:
> 
> o. Tinymail is not a C software where every file plays its own isolated
>    significant role. It's a design with a bunch of implementations. A
>    lot of them cooperate and call upon each other's functionality.
> 
>    Changing for example an API involves changing multiple files. 
> 
> o. Software developers who want to get into Tinymail software
>    development should therefore learn about its design, not focus on
>    individual changes in .c files.

The ChangeLog is meant to help developers see what's changed, not
provide information about overall design. "bugfixes" does neither.

>    I find it better to document the changes on the development trac
>    wiki, than to try to document it in (only) the ChangeLog.
> 
>    By that I mean:
> 
>    To document them using class diagrams and/or enough words to fully
>    describe both the change AND the concept / design.
> 
>    The ChangeLog, though, would be useful for referring to that page,
>    indeed.
> 
> o. It causes the ChangeLog to become enormously big and more difficult
>    to read. Although this is my opinion only. There are indeed probably
>    a lot of tools that reduce this problem.
> 
>    I also agree that for some changes, it does make good sense to use
>    the notation with filenames.
> 
> 
> When and when not to add a changelog entry
> 
> o. Best practise: always, every commit. Although .. let's be pragmatic:
> 
> o. I'm in favour of seeing all changes, also minor ones, to be recorded
>    in the ChangeLog. Although I only require real changes to be in the
>    ChangeLog (but I do require those).
> 
> o. Tinymail's Subversion is not a spartan "one commit is one feature":
>    It's a development tool and people should quickly and freely commit
>    in trunk.
> 
> 
>   I will create branches and tags when certain milestones are reached, 
>   the developer does not have to leave the repository in a certain state
>   of "quality". Although bugfree commits are of course encouraged.
> 
> 
> Further ...
> 
> I don't see truly bugfree commits as a practical way forward. I see such
> a rule as a pure development blockage. Something that I, as Tinymail's
> project leader, will not allow.
> 
> The way is forward, it's not standing still on each and every patch, and
> do a lengthy review process. Having a bugfree product does not happen by
> spartan punishment and endless reviewing of patches.
> 
> Software development should be fun, quick and social.
> 
> A bugfree product happens using tools like continuous integration, unit
> testing, design by contract, proper design in general, setting certain
> milestones, keeping track of bugs and building tests around old and
> existing bugs (so that other bugsfixes don't reintroduce an old
> bug), ... by using the right tools (gdb, valgrind, etc)
> 
> A bugfree product happens while trusting your developers and their
> commitment and desire to fix their own bugs. A software developer who
> wrote a bug just didn't know that he or she did. That's why we need as
> much tools as possible to early-detect said bugs.
> 
> The methodology for Tinymail, therefore, is "as Agile as possible".
> 
> I don't believe in the old "opensource" methodology of "extremely
> correct patch to mailing list", "review", "commit"
> 
> I have SEEN it being dis-functional and I have felt and SEEN it
> discourage software developers from contributing multiple times.
> 
> 
> ps. I indeed hope that I don't have to write "rules" E-mails like this
> one too often.
> 
> 
> Finally:
> 
> If a company does not like these policies, I hereby invite those
> companies to start using the release branches as soon as I launched
> Tinymail's first release.
> 
> I will with spartan rule guard the API, ABI, ChangeLog and changes that
> will go in such branches.
> 
> 
-- 
Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com