Difference between revisions of "CVS Etiquette"

From Audacity Wiki
Jump to: navigation, search
(my first draft from my perspective)
(No difference)

Revision as of 07:48, 24 April 2008

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.

General

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.