Getting Started

Some basic knowledge about Python and development tools like diff is required. Your best bet is to start with a fresh source code snapshot, which you may obtain from our Subversion repository (see instructions here).

Version control history can be obtained using Subversion clients, but is also browsable using tigris.org's integrated ViewVC tool.

Testing and Reporting

Testing usability and the installation process on different platforms is also a valuable contribution. Please report your results back to us developers. Bandwidth is getting cheaper daily, so don't be afraid — in fact, feel encouraged — to dump as much detail about the problems you are seeing as possible into your bug reports. Here are some things you definitely should try to include:

• What version of ViewVC you are using (if you are using a source snapshot, tell us the date of that snapshot).
• What operating system your ViewVC is running on.
• What version of Python you are using.
• Whether you are running ViewVC standalone, or as a CGI program under a web server (and if so, what web server).
• The URL of your ViewVC instantiation, if it is public. Sometimes, letting developers see the problem for themselves can save everyone alot of time.

Coding Style

Unlike its predecessor, CvsWeb, ViewVC is written in Python, so it doesn't suffer from the "unmaintainable code effect" that hits most Perl projects sooner or later:

"[Perl] combines all the worst aspects of C and Lisp: a billion different sublanguages in one monolithic executable. It combines the power of C with the readability of PostScript." — Jamie Zawinski

Of course, a symphony of insanity can be composed in any language, so we do try to stick to some basic guiding principles. Maintain whatever style is present in the code being modified. New code can use anything sane (which generally means PEP 8). Our only real peeve is if someone writes a function call as: some_func (args) — that space between the function name and opening parenthesis is Huge Badness. Oh, and we do not use Subversion keywords (such as $Id$) within the source.

Otherwise… shrug.

Submitting Patches

Nothing speaks more loudly when bugs or features are the topic than a patch. And quite frankly, sometimes if you want something done, you gotta do it yourself. So, patches are always welcome. If you aren't sure what exactly a "patch" is, or don't know how to generate one, but you've got code contributions to make, please don't hesitate to ask questions on the mailing lists. Patch generation and application are pretty easy thing to get the hang of, and drastically simplify code submission and review.

Please use the Issue Tracker to submit your patches. Unified contextual diffs against the latest development snapshot are preferred.

If you have commit access, then you should know what you're doing. Just make changes directly. Subscribing to the dev@ developer mailing list is recommended in any case.

Security

Since ViewVC is used on the Internet, security is a major concern. If you need to pass data from the request into an external program, please don't use os.system() or os.popen(). Please use the module lib/popen.py that is included in the ViewVC distribution instead.

Adding Features

If you need a new configuration option think carefully, into which section it belongs. Try to keep the content of cgi/viewvc.conf.dist file and the library module lib/config.py in sync.

Because ViewVC is a Web-based application, people will have ViewVC URLs hyperlinked from other sites, embedded in emails, bookmarked in their browsers, etc. It is very important to ensure that those URLs continue to retrieve the information they were intended to retrieve even if ViewVC is upgraded on the hosting server. In other words, as new features require modifications to the ViewVC URL schema, make sure those modifications preserve the existing functionality of all ViewVC URLs.

The library subdirectory contains a module debug.py, which you may find useful for performance testing.

If a new file or module is added, a new line in the installer program viewvc-install is required.

Hacking on Templates

The library module ezt.py contains a module docstring which describes the directives used in the HTML templates used by ViewVC. The templates themselves can be found in the templates subdirectory. We're currently developing a how-to guide for ViewVC template customization.

Release Management

There is a script, tools/make-release, which creates a release directory and the various archive files that we distribute. All other steps required to get a ViewVC release out of the door require manual execution (currently by C. Michael Pilato). Those steps are as follows:

1. Add a new subsection to the file website/upgrading.html describing all user visible changes for users of previous releases of ViewVC.
2. Update the CHANGES file
3. Update the website/index.html file to refer to the new X.Y files. (there are three links to update)
4. Edit the file lib/viewvc.py and remove the "-dev" suffix from __version__. The remainder should be of the form X.Y.Z, where X, Y, and Z are positive integers.
5. Ensure all of the above changes have been committed.
6. Test, Test, Test! At the time of this writing (1.0-dev) there is no automatic testsuite available. So just run with permuting different viewvc.conf settings… and pray.
7. Review any open bug reports.
8. Use svn cp to tag the release to /tags/X.Y.Z, where X, Y, and Z should be replaced by the release number from above. If a developer is willing to volunteer as a bug fix patch release manager, it is now possible to start here at this point with a feature-frozen branch using svn cp to copy the tag to /branches/X.Y.x.
9. Go into an empty directory and run tools/make-release viewvc-X.Y.Z X.Y.Z. This step requires read access to the Subversion source code repository.
10. Upload the created archive files (tar.gz and zip) into the Files and Documents section of the Tigris.org project.
11. Edit the file lib/viewvc.py again and this time increment the __version__ for the next release cycle, again append the -dev to the version and again svn commit -m "Begin a new release cycle." lib/viewvc.py.
12. Write an announcement explaining all the cool new features and post it announce@viewvc.tigris.org, to the project's News area, and to other places interested in this sort of stuff (such as Freshmeat).