CVS Etiquette

General

 * Subscribe to the, 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.


 * Subscribe to the not only so you see when other people make changes to the code base, but so that your own changes get sent to the list subscribers.


 * Bookmark so you can view the source tree sorted in date change order.

The cvs command also 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. If you have TortoiseCVS on Windows, right-click on the file in 'Explorer' > CVS > Annotate. As always, check the documentation for your own interface client.

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
Before committing major changes, it's good practice to purge out all compiler warnings at the highest warning level on the original platform. This catches a remarkable amount of problems which may not be fatal on this platform but may be elsewhere. Make sure that forced includes and precompiled headers are turned off, as they can hide build issues with missing header files.

If your code change does break something else, it's often useful to get back to a specific date in the code when it worked. This way, you can backtrack to when it worked and then take steps forward again, fixing as you go. TortoiseCVS has an "Update Special..." command (right-click in Explorer > CVS > Update Special) that lets you easily synchronize a local sandbox with the state of the repository at a specific date/time, or to a specific branch/tag/revision.

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.

Some breakage is inevitable when files are added / removed, in which case we try to post a list of file changes to the mailing list to make updating the other build systems easier.

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.