One commit = one change
ryandesign at macports.org
Mon Mar 5 17:27:05 PST 2007
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:
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
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.
The log message here says that livecheck was added, but also the
software version was increased, which the log didn't say.
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
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.
More information about the macports-dev