CVS Etiquette

From Audacity Wiki
Revision as of 13:22, 24 April 2008 by Richardash1981 (talk | contribs) (External Libraries: add a description of how I work with the lib-src/ tree)
Jump to: navigation, search

This page tries to summarise how the audacity development community uses the project CVS repository. It is descriptive rather than policy - it describes how things are at the time of writing, rather than attempting to prescribe how things should be. As such, it should only be edited by users of the CVS repository.


Be subscribed to the audacity-devel mailing list, because that is where information and discussion about the repository is likely to be. It's here that people will ask about your changes, provide feedback and warn you of upcoming changes.

Use cvs diff to check that what you think you are committing is what you want to commit. Make sure that temporary debugging code has been cleaned up, and the comments are up to date with what the code does (as far as possible).

Stay up to date - bug reports against weeks old CVS are unlikely to be helpful, and may well have already been fixed.

Commit incrementally. Don't mix up unrelated changes in the same commit, and try to make sure that each change you make gets committed quickly, rather than letting your working copy get out of sync with HEAD and having to merge lots of changes.

Build Breaking

Sometimes a change on one platform, especially when it affects the build system (makefiles, project files etc), will result in updates being needed for all the other platforms audacity supports as well. Very few audacity developers have access to all the operating systems needed to make these changes for themselves, so we have to rely on other people updating the other platforms.

Changes in Audacity Code

For changes in Audacity itself and the libraries we maintain (libresample, FileDialogue) we assume that you know what you have changed on your platform and so what will need changing on other platforms in the way of adding new files etc. In this case send an email to audacity-devel saying what has changed and what needs to be done to fix it (e.g. "I've added new files Foo.cpp and Foo.h, they are included in the Makefiles, but need to be added to the Visual Studio and Xcode projects").

Updates in Lib-src

When updating external library copies in /lib-src/ it's likely that you don't know file by file what has changed, so you probably will have to either trust the upstream developers to have an up to date project file (and let people know to use it), or just say that you have updated the library an the build system will need work. This mostly affects project files because all of audacity's external libraries come with configure scripts from upstream. See also the section on Updating Libraries below.

Platform Specific Code

There is sometimes a conflict between trying to follow the conventions of each target platform closely, and providing a consistent look and feel to audacity regardless of where it is running. Trying to follow the former path can lead to lots and lots of #ifdefs to re-arrange the code for each platform, and can make it hard to read. This topic is also a good way to produce a heated discussion which achieves relatively little.

As a first preference, try to find a wxWidgets function that does what you want to do in a platform-independent manner, rather than using OS-specific functions wrapped in #ifdefs.

In general, it's not worth disabling features on some platforms on the basis that they are "non-standard", provided that they work. A good example is using environment variables to adjust the search paths for plug-ins. This is normal on Unix-based systems, but very rare on Windows. Given that it works (using wx functions to get the environment variable) on windows, there is no reason to disable it, although very few people will ever find it.

External Libraries

One of the most powerful features of open source is the huge range of libraries available for almost any function under the sun, which saves us from having to re-invent the wheel. With this tremendous labour saving however, comes some effort to integrate libraries into audacity.

Linux users will have almost any library that we might use available on their system via their distribution, and installing it will be a quick and painless experience in nearly all cases. This tends not to be the case for Windows or (to a lesser extent) OS X users, because there is no standard way of getting libraries for those systems. For this reason audacity keeps copies of many of the libraries used within the audacity CVS, so that they are all available when compiling on those platforms. The executables we distribute are also statically linked so that users don't have to install the libraries in order to install audacity.

These copies of other people's libraries are all located under lib-src/ in the audacity CVS, and managed slightly differently from the rest of the code. As far as possible, we don't modify these libraries to use them with audacity. This is important so that when users try to compile audacity with the original versions they can do so, and so that when the authors of the libraries release new versions of the libraries we can update easily and painlessly. If we do have to change a library (e.g. because it doesn't compile on one of our platforms, or because of a bug) then we try hard to make sure that the change is passed back to the authors of the library so that everyone else can benefit from it. Realistically, this can take a while so we will often have to include changes in our CVS copy until a new release comes out with the fixes.

To make this process easier to keep track of, there is a file in CVS called lib-src/audacity-patches.txt. This file contains details of what version of each library is currently in CVS (so we can see if they need updating), and lists any patches which have been applied and what the status of those patches is. The patched themselves are checked in to CVS within the library directories until they are accepted and no longer needed. In general it is the responsibility of whoever commits the changes to audacity CVS to make sure that the patches are set to the library authors.

At the bottom of the file is a set of instructions on updating the library copies in CVS to make the process run smoothly. This can be a very good way to stop audacity compiling, so make sure that you read the section on Build Breaking above.