Re: Changelog formatting and project rules
- From: Murray Cumming <murrayc murrayc com>
- To: Philip Van Hoof <spam pvanhoof be>
- Cc: tinymail-devel-list gnome org
- Subject: Re: Changelog formatting and project rules
- Date: Tue, 29 May 2007 13:52:08 +0200
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
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]