Changelog formatting and project rules

[Philip Van Hoof <spam pvanhoof be>]

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.

   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.


-- 
Philip Van Hoof, software developer
home: me at pvanhoof dot be 
gnome: pvanhoof at gnome dot org 
http://www.pvanhoof.be/blog