One commit = one change

[Juan Manuel Palacios]

On Mar 5, 2007, at 11:22 PM, Yves de Champlain wrote:

>
> Le 07-03-05 à 20:27, Ryan Schmidt a écrit :
>
>> Dear MacPorts committers,
>>
>> I've seen a lot of commits to portfiles that do more than one thing. 
>> For example, a commit that updates the port to a new version, adds a 
>> new variant, and changes the indentation of the entire file. This 
>> makes it incredibly difficult to see what actually changed, and I 
>> would very much appreciate it if we could get into the habit of 
>> committing each logical change separately.
>>
>> For example, if you want to change the indentation of the file, do 
>> only that, then commit it, with a log message that says you're 
>> changing the whitespace. If you want to upgrade to a new version, do 
>> just that, and commit it with an appropriate log message. If you want 
>> to add a variant, do that, and commit it. This way it is much easier 
>> to look through the Subversion log and especially the diffs and see 
>> what was changed and why. If you do it all at once in a single 
>> commit, especially whitespace changes which like to affect every 
>> line, it's very difficult to see what was really changed, and this 
>> hinders people like me who are trying to learn more about MacPorts, 
>> portfiles, and compiling software in general.
>>
>> Hand in hand with the idea of one change per commit is the idea of 
>> accurate log messages. Your Subversion log message should say exactly 
>> what you changed. Don't omit anything!
>


	This is a logical and sane petition by Ryan that we should all try to 
meet to guarantee the best communication possible between us all. 
However, as many of you have pointed out already, it is difficult to 
achieve and therefore a balance should be sought, chiefly what Yves 
points out below: sometimes one change per commit makes no sense and 
might even be impossible, sometimes that's exactly what the type of 
change mandates; all in all, I believe the moto should be "one logical 
block of changes == one commit", that logical block of changes be 
whatever the maintainer was working on as the next & inseparable 
feature set of the Portfile (version upgrade, version upgrade & new 
variants, just new variants & new maintainer promoting them, whatever), 
but no more than that.

	Needless to say, the log message should be as detailed as possible, 
but concerning only the changes made to the Portfile, not the ported 
(or upgraded, or revised, or whatever...) software. Citing the mpfr 
example given somewhere in this thread, a commit log detailing what 
each added patch does would be totally overkill; instead, a log simply 
listing the added patches and, if available, providing URLs to 
descriptions on each of them would be preferable.

	Regards to all and thanks for bringing this topic up, this is the type 
of thing we need to discuss as a group to improve our communication 
flow! All the best,...


-jmpp



> Hi
>
> This sure makes sense, but it does not really fit with how a Portfile 
> is worked.  For example, I recently updated e17 stuff and had to 
> change versions, dependencies, configure environment and arguments, 
> and I finally decided to also opt in as maintainer.  But there is no 
> "logical order" to do this.  1 commit / change would have meant 
> artificially creating many versions of the Portfiles afterwards with a 
> few changes in each one.
>
> However, it is true log messages should be very clear as to what is 
> happening. i.e.
>
> bump to version ...
>
> change configure.env ...
>
> change deps ...
>
> change configure.args ...
>
> change maintainer ...
>
> Lots of changes, but everything is written clearly.
>
> yves
>
> _______________________________________________
> macports-dev mailing list
> macports-dev at lists.macosforge.org
> http://lists.macosforge.org/mailman/listinfo/macports-dev