Aaron S. Hawley (aaronhawley) wrote,
Aaron S. Hawley

Logging the changes

All software needs to have a manner to document the edits made to source files over time. Typically, there is a Changelog file distributed with a software's source package, popularly named ChangeLog and following the GNU ChangeLog conventions.

Most software projects also use a version control system, which in addition to tracking the line-by-line changes to a file, they also require a developer add a description for each change, very analogous to the entries of a ChangeLog file.

But even with version control software -- like CVS, Subversion and Git -- ChangeLog files will probably not go away. The public can easily access the revision history of many a free software project. Regardless, I predict separately maintaining the change history of a source package and shipping the ChangeLog file with a source tar-ball will not go away anytime soon.

There should always be a low hurdle for users to determine what has changed in a new release. Further, contributions to software are often made outside the software project's coterie. The request is often made of contributors, "Please include a ChangeLog entry with your submitted patch." ChangeLog file's also stick around because people rely on them. The format of ChangeLog files are really easy to read once you get used to them.

The problem is that the relation between version control software and ChangeLog files isn't automatic enough as it should be. There can never be a complete and binding relationship between version control log entries and the ChangeLog file. For example, some version control entries should not and do not translate well to a ChangeLog file -- and that's ok. This is why the batch-operating commands -- like rcs2log, cvs2cl, svn2cl -- don't work well enough. After running these commands, the ChangeLog file still usually needs to be hand-edited.

In Emacs, ChangeLog support is quite successful. There is a ChangeLog Mode that supports the unique syntax well, and can also automatically generate entries in the closest ChangeLog file. It formats the entry based on either the location in a source file or a diff file. You really have to see it to believe it.

Unfortunately, Emacs doesn't coordinate its ChangeLog features with its equally impressive version control features. It does have the batch-oriented commands that I previously mentioned.

Eric Ludlam of CEDET fame, has come up with an Emacs command for populating the log entry buffer with entries palpable for ChangeLog. It's an interesting solution to the problem.

Unfortunately, on the projects I work, I usually work on the ChangeLog file before I make the commit. So, I'd prefer to go the other direction, edit my ChangeLog file and have them populate the revision control logs.

However, perhaps Ludlam's solution is the way it should be.
Tags: emacs, free software, programming, unix
  • Post a new comment


    default userpic

    Your reply will be screened

    Your IP address will be recorded 

    When you submit the form an invisible reCAPTCHA check will be performed.
    You must follow the Privacy Policy and Google Terms of use.