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 CVS Repository
at SourceForge.
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 ViewCVS you are using (if you are using a source
snapshot, tell us the date of that snapshot).
- What operating system your ViewCVS is running on.
- What version of Python you are using.
- Whether you are running ViewCVS standalone, or as a CGI program
under a web server (and if so, what web server).
- The URL of your ViewCVS instantiation, if it is public.
Sometimes, letting developers see the problem for themselves can
save everyone alot of time.
Coding Style
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 CVS keyword macros (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 SourceForge
patch manager 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 developer
mailing list is recommended in any case.
Security
Since ViewCVS 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 ViewCVS
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/viewcvs.conf.dist file and the library module
lib/config.py in sync.
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 viewcvs-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
ViewCVS. The templates themselves can be found in the
templates subdirectory.
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 ViewCVS release out of the door
require manual execution (currently by Greg Stein). Those steps
are as follows:
- Add a new subsection to the file
website/upgrading.html describing all user visible
changes for users of previous releases of ViewCVS.
- Update the
CHANGES file
- Update the
website/index.html file to refer to the
new X.Y files. (there are three links to update)
- Edit the file
lib/viewcvs.py and remove the
"-dev" suffix from __version__ . The
remainder should be of the form X.Y, where X is a positive
number and Y is a single digit.
- Ensure all of the above changes have been committed.
- Test, Test, Test! At the time of this writing (1.0-dev) there
is no automatic testsuite available. So just run with
permuting different
viewcvs.conf settings…
and pray.
- Review any
bug reports, that are still marked open.
- Run
cvs tag VX_Y , where
X and Y 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 freezed branch using cvs tag -b
VX_Y_maint
- Go into an empty directory and run
tools/make-release
VX_Y viewcvs-X.Y . This step requires
anonymous CVS access to repository at SourceForge.
- Pack the content of this
viewcvs- X.Y
directory into a tarball.
- Upload the created tarball into the download files section of
the ViewCVS project at SourceForge:
scp viewcvs-X.Y.*
USERNAME@viewcvs.sourceforge.net:/home/groups/v/vi/viewcvs/htdocs
- ssh to viewcvs.sourceforge.net, cd to the above directory,
and do a "
cvs update " to pull down the latest
website files.
- ftp to upload.sourceforge.net, cd to the
/incoming directory, and upload the .gz and the
.zip
- go to the Admin pages for the ViewCVS project, and go to
"Edit/Release Files"
- select "Add Release" and fill in the new release name
(X.Y)
- fill in the Change Log section with the relevant portion from
the
CHANGES file and select the "Preserve my
pre-formatted text" option. (and Submit those changes)
- the files uploaded to upload.sourceforge.net should appear in
the "Add Files To This Release" section. Select them, and add
them.
- for each file: change the processor type to "Any", select
"Source .zip" or "Source .gz" as appropriate, and hit the
Update button. (note: you need to Update each file
separately)
- after about 15-30 minutes, the files will appear on the Files
page of the project.
- select the "I'm sure" button and hit the "Send Notice"
button.
- NOTE: if you need to hide a prior release, then go back to
the admin page and follow the links for editing a
release. Change the "Status" drop-down to "Hidden" and
submit the change.
- Edit the file
lib/viewcvs.py again and this time
increment the __version__ for the next release
cycle, again append the -dev to the version and
again cvs commit -m "new release cycle begins"
lib/viewcvs.py .
- Write an announcement explaining all the cool new features and
put it out to:
|