CommitterGuidelines

Committer Guidelines

Contact: KenManheimer

Getting write access entails responsibility along with trust. The viability of any substantial software effort ultimately depends on the developers good judgment, it's all the more crucial in a widely distributed physical and organizational effort like this.

ZenFromZopeCoders has some orientation, harvested from early discussion on the Zope-coders mailling list. Eventually this may be factored into the ZopeCVSFAQ, but in the meanwhile you may want to check it out.

Who Does What

Zope Corp. CVS managers assign CVS project managers with authority to recruit committers for their project. Along with the authority over that access, the project managers have responsibility for their project members. If they're uncomfortable with a member's behavior, they can rescind their access privileges at any time.

The project managers, in turn, answer to the CVS repository managers - currently Brian and Ken.

Ultimately, everyone's responsibility is to the Zope community, both inside and outside Zope Corp., to keep Zope projects in the repository moving forward smoothly.

Authorities and Responsibilities

Project managers have authority over write access to their repository, and responsibility for the actions of the people they grant access to. The manager has the prerogative to revoke their project members access privileges at any time they feel it's warranted.
(It is, of course, in everyone's interest for members to cooperate with the managers and their colleagues in the project. Manager's authority is for boundary cases, when problems go offscale.)
Project members are intended to make changes only within their project areas. We expect the people with write privileges to know the bounds, and to not trespass beyond them. Failing to recognize the bounds is a prime reason to lose all access.

Global Coordination

Every committer should enlist in the zope-coders mailing list - visit http://lists.zope.org/mailman/listinfo/zope-coders . It's the primary channel for urgent operational issues - things like release checkin freezes, operational problems, warnings about major-checkin upheavals, and so forth.
It is also a channel for collaboration between the committers. As such, it may be of interest for others to follow, so anyone can subscribe - but non-committers should refrain from posting unless they have really really good reasons to do so.

(Anyone can always use zope-dev for general discussion - we're want the input, just don't want to burden zope-coders bandwidth with it.)
Committers are strongly encouraged to monitor the Zope collector traffic, via the zope-collector-monitor mailling list . This traffic is a key channel conveying Zope problems, providing both feedback about the health of the development process and a wealth of information about areas of concern and opportunity. The more informed attention we have on these issues, the better!

What Goes Where, and Making Structural Repository Changes

The repository consists of applications and also directories of elements which can be shared among the applications. Anyone making additions to the repository must understand the sharing arrangements, to know the right place to put things.

See WhatGoesWhereAndHow for details.

Checkin Standards and Practices

NOTE that ZopeCVSFAQ has instructions for key CVS operations for you're likely to need for dealing properly with our repository.

Project managers set the standards for their section of the repository. We have some required practices for the Zope-specific section. Some are common sense and generally applicable, while some are more specific to the application. (See ZopeReleasePolicy for the whole scoop.)

In the Zope area, no actual development work may happen on the "trunk". All development activity happens in unique branches, and are merged into the trunk only when the work is stable enough to be included in the next beta release. The trunk should never be in a state where we would be uncomfortable making an alpha or beta from it on 2 days notice.
The ZopeCVSFAQ provides definitive guidance on using branches this way. If you're working on the Zope project, or any project using this practice, it's required reading.
Be sure about your changes before creating them.
All substantial Zope changes must be agreed upon in a fleshed-out Fishbowl Proposal before they are implemented.

Other options may make sense for smaller changes. It may be sufficient to post a tracker issue outlining the change - or the change may actually be a bug fix of small feature resulting from an issue consultation.

This communication can help avoid going off in the wrong direction. Getting forgiveness may be harder than getting permission, when it comes to cleaning up undesired and inappropriate changes after they're committed.

Committers need to be careful about what version of Python their changes require. In general, Zope requires Python 2.1, so it's safe to use any feature present in Python 2.1. But certain packages are also used separately from the Zope release and need to work with older versions of Python. See PythonVersionRequired for details.
Test your changes before committing them.
Except for very sweeping changes, most can be adequately tested within a checkout before checking them in. This means that most of the time you should be able to avoid disrupting others with your changes. Careful testing before checkin is good hygiene in software development - without it, disease and failure can spread.

We are accumulating a comprehensive test suite, and ironing out the details. Once established, it will be unacceptable for any code checkins to cause the test suite to fail. (If a checkin causes a failure, it will have to be fixed within 24 hours or it will be backed out.)

See ZopeTestingGuidelines for the (emerging) story.
Develop unit tests for every new feature (and for old ones not yet covered)
One corollary to the last item is the great value of unit tests. They're no miracle cure - they take effort, and can't catch everything - but they can be used to bring the stability of an application across change to a qualitatively higher level. Much encouraged. (If you know some prime unit tests references, link them in to comments at the bottom, and i'll weave them into the text.)

There's a proposal towards some likely principles for our unit testing approach - see http://dev.zope.org/Wikis/DevSite/Proposals/CleanUpAndUnifyCoreUnitTests

Again, see ZopeTestingGuidelines for the (emerging) story.
Followup promptly on problems with changes you've made.
Breaking things off-the-bat is often poor conduct, to some degree but not totally compensated by diligent effort to rectify the problems. Much better, when possible, to test adequately and not break stuff at all.

Beyond that, every change entails some degree of ongoing responsibility. Others may eventually be able to step in and take over your code, but you may need to shepherd it along while it's getting absorbed in the common understanding.
Coding Details:
- No lines greater than 79 chars unless unavoidable
- In python, use spaces for indentation, preferably 4 spaces per level. If you must, use 8-column tabs - but don't combine tabs and spaces. Checking in files that use both tabs and spaces for indentation can be considered checking in buggy code, warranting demand for repair and karmic blemishes that need not be tolerated for long...
- In general, we encourage following the Python coding style suggested by http://python.sourceforge.net/peps/pep-0008.html and the C style in http://python.sourceforge.net/peps/pep-0007.html

jshell (Aug 6, 2001 6:05 pm; Comment #1)

Regarding unit tests, some good pages are out of a (can't believe i'm about to admit this) wiki, the great c2.com wiki.

jshell (Aug 6, 2001 6:08 pm; Comment #2)

Oops. And there's the Python specific documentation (covering a more recent version of unittest.py than is in Zope 2.4.0 and earlier):

stevea (Oct 1, 2001 6:00 pm; Comment #3) Editor Remark Added

I'm adding a digest of the Zope-Coders list to date at ZenFromZopeCoders.

klm Oct 1, 2001: Excellent! It might should eventually be integrated with the ZopeCVSFAQ, but in the meanwhile i've put a link to it at the top of this page. Thanks!

faassen (Oct 18, 2001 6:28 pm; Comment #4)

I'm creating a page on the Zope automatic (unit) testing guidelines at ZopeTestingGuidelines. I'd add it to ZenFromZopeCoders but only owners can edit these pages, it seems.

klm Nov 19, 2001: I've added it to the main body of this page.

jeremy (Oct 22, 2001 9:22 pm; Comment #5)

PythonVersionRequired: Committers need to be careful about what version of Python their changes require. In general, Zope requires Python 2.1, so it's safe to use any feature present in Python 2.1. But certain packages are also used separately from the Zope release and need to work with older versions of Python.

klm Nov 19, 2001: Thanks - i've added this note to the main body of this page.

yuppie (Nov 20, 2002 5:06 am; Comment #6)

Style Guide PEPs? have moved. New location: