CVS Etiquette

From Audacity Wiki
Revision as of 07:41, 25 April 2008 by Richardash1981 (talk | contribs) (Useful tips: add link to tips and tricks page)
Jump to: navigation, search
This page summarises how the Audacity development community uses and maintains the project CVS repository, and serves as a guide for those new to committing code changes via CVS. 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 those with shell access to 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 code changes, provide feedback and warn you of upcoming changes.

Be subscribed to the audacity-cvs mailing list  so you see when other people make changes to the code base.

Just before you commit, update your local copy of the code from CVS and then compile and check your changes still work. This makes sure that incompatible changes are not made. Do not commit without doing this. If somebody else is making a bunch of changes and you can't do the above reliably (have a look at the audacity-cvs list), wait until tomorrow.

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).

If you are nervous about making your first change to CVS (we all were!), why not change \audacity\win\sandbox.txt? Add a 'hello world', joke, or whatever? Nobody is going to mind - that's what it's for.

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 and so on. In this case send an email to audacity-devel saying what has changed and what needs to be done to fix it. An example: "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 and the build system will need work. This mostly affects IDE project files (Windows and OS X) 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 third-party 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 (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 patches 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 audacity-patches.txt 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.

Useful tips]  is a good place to bookmark. It's the most likely place to go to find the history of what you are looking at.

'CVS Annotate' is very useful to see when a file was changed, by who and when. It helps to get a feeling for what was introduced as a major change, who's been bug fixing and where etc., and helps you get into the right place in the above if you need to. If you have TortoiseCVS that's a right-click on the file in 'Explorer' -> CVS -> Annotate... , probably something similar in other tools.

'CVS -> Update Special...' is also useful to get you back to a specific date on the code when it worked. If something goes pear-shaped you can back-track to when it worked and then take steps forward again, fixing as you go. You don't want to be there but maybe.

See also the CVS Tips and Tricks page.