One commit = one change

[Ryan Schmidt]

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!

Just looking at some of the recent commits to the repository:


http://trac.macports.org/projects/macports/changeset/22590

The log message says the port was updated to a new version, but also  
the maintainer was changed, which IMHO should have been a separate  
commit.


http://trac.macports.org/projects/macports/changeset/22583

This revision updates the port version, changes the maintainer,  
changes whitespace, and adds the livecheck feature. I would have  
preferred separate commits, but at least the log does say that all of  
that was done.


http://trac.macports.org/projects/macports/changeset/22543

The log message here says that livecheck was added, but also the  
software version was increased, which the log didn't say.


http://trac.macports.org/projects/macports/changeset/22515

The whitespace of most of the file was changed, the maintainer was  
changed, the configure args were changed, and some patches were  
added, though it doesn't say why or what issue they were supposed to  
fix.


I don't mean to be singling anybody out with the above commits;  
they're just some apt recent examples I found. I also should point  
out that I do most certainly thank all the MacPorts committers, since  
I am very much benefitting from all your hard work. But I not only  
use MacPorts to install software on my machine, I also like reading  
the portfiles to see how things were done, and especially, looking  
through the changes that were made to portfiles, and to read about  
why those changes were done. This is where one-change-per-commit and  
accurate (and, where appropriate, even detailed) log messages are so  
important, which is why I bring it up.