This reference manual is intended to give an overview of the processes and conventions of the development of Plone, both as a point of reference for existing developers, and a source of explanation for new developers.

It is not intended as a general guide for how to develop applications on top of Plone, but some of the "best practice" documentation here may be useful to third party developers as well.

This document is a work in progress, and will probably continue to be so for a good while. We will endeavour to publish pages and sections when they are complete, but don't be surprised if you find that there are major pieces of the puzzle missing at present.

Like all open source products, Plone only moves forward on the contributions of volunteers. If you would like to contribute, we will be incredibly happy!

However, there are many people and companies who rely on Plone day-to-day, so we have to introduce some degree of quality control over the code base. Plone's source code is hosted in an open Subversion respository on http://svn.plone.org, but only members of the developer team have commit-rights. Before you can get commit rights, three things need to happen:

1. You must familiarise yourself a little with the community. Get on the chatroom, start asking and (especially) answering questions on the mailing lists, and get to know the more active developers a bit. If you arrive in the #plone chatroom and ask how you can help, chances are you will be met with gratitude and openness, so don't be afraid to introduce yourself. If no-one answers, it's probably just a bad time of the day: try the developers' list instead.
2. You must prove that your code does not suck. There are two types of people in the world - those who can write code, and those who cannot. Actually, we take that back - there are also UI people. And accessibility experts. And translators. And documentation writers. And testers. However you wish to contribute, though, we'd like to see the calibre of what you produce. See below for ways of contributing without commit-access to the source code repository.
3. You must sign the contributor agreement. This offers some intellectual copyright protection, and ensures that the Plone Foundation is able to exercise some control over the codebase to ensure it is not appropriated for someone's unethical purposes. Think IBM vs. SCO.

Now, there are a number of other ways you can help out, which do not require contributor agreements or anything else than the right attitude.

Testing

We always need more testers. If you believe you have found a bug in Plone, particularly if you are using a less common operating system, have a very large site, or operate in non-English locales, please report it in the bug collector. Please search the tracker thoroughly before submitting a bug, so that we avoid duplicates.

Before submitting a bug, please log in with your plone.org username. If you don't have an account, just click the "join" link in the blue bar at the top on plone.org. You can submit bugs without being logged in, but when you are logged in, you will be given email notification when your bug is responded to. This is important if we need clarification, for example - you can see a request for clarification, and then add a follow-up with more details.

Please think carefully before submitting a bug. If the bug is really in a third party product, do not use the Plone tracker, as we won't be able to help you - contact the authors directly, instead, or use their tracker in the products area. If it is a Plone bug, search for similar issues and add a follow-up to an existing bug if necessary - we will be notified of this just as clearly as with new bugs.

If you have to submit a new bug, try to write as clearly and concisely as you can to ensure that we understand your problem. Include relevant product versions, and always enter your Plone and Zope versions. Be honest about the severity - submitting a bug as "critical" if it is not is unlikely to win you any sympathy.

Patches and verification

Very often, issues end up in the collector for a long time because we don't know whether there was actually a problem, or if the submitter was experiencing a local configuration issue. If a bug looks sketchy, it's very helpful if you can try to replicate the problem on your own setup and add a follow-up about your experiences. If you have more insight to offer than original submitter, this is of course incredibly useful!

If you think you know how to fix a bug, this is your chance to shine. Once logged in, you can submit patches to the tracker. Even if you can't provide a patch, but can do some research and come up with a way in which the issue may be resolved easily, this will help the developers immensely. Adding patches to the collector is one of the best ways of showing off your skills and proving that you should be given commit-access to the Plone repository.

Documentation

Any member of plone.org (that includes you, if you want to be) can submit documentation to the Plone documentation area. If you have discovered something that you feel was poorly documented, you will gain much praise by writing a short How-to or a Tutorial on the subject. Once you are finished, submit your document for review, and we will publish it if it is not giving bad advice or too difficult to understand. You will probably find that writing documentation also helps you structure your own understanding of Plone, and forces you to consider issues you may have otherwise glossed over.

If you need help with writing documentation, or you're not sure where to start, send a mail to the plone-docs list/newsgroup

Helping others

The best way to gain respect in the community is by helping others. If you spend some time in the #plone chatroom or on the Plone users' mailing list answering people's questions when you know the answer, people will take notice. Helping others will help your own understanding, not to mention the warm fuzzy feeling you'll get afterwards.

General

Plone uses a time-based release process, which helps to produce releases of predictable size and complexity. In order to make this work there are some requirements on how new features get accepted and implemented.

Special roles

There are some special roles in the Plone community of which the release manager and the framework team are the two important ones for the release process. For every release a release manager is elected by the Plone foundation board who has the authority to make certain final decisions for a release. The framework team is a group of people who assist the release manager in the process of reviewing any suggested features.

Release phases

The normal development cycle of a Plone release consists of various phases. See the Plone roadmap for concrete dates for the next upcoming releases.

Discussion and Planning

People suggest new features and discuss them. We use a lightweight formal process which helps to foster and document this. See the below paragraph on enhancing Plone for the details.

Proposal freeze date

For each release there is a certain date by which all new feature proposals must have been submitted for review. After this date no features will be accepted anymore for this particular release.

Alpha releases

We will release various snapshots of the current release bundle that we package up to give out for testing. Migration to/from specific alphas is not supported.

Feature freeze date / Beta releases

By this date all features must have been completed and all code has to be integrated. Only non-invasive changes, user interface work and bug fixes are done now. Migrations supported to/from specific betas.

Release Candidate

Ideally, the last beta that was bug free. No changes to the code. Should not require any migration steps apart from the ones required in the betas. If any problems are found and fixed, a new release candidate is issued.

Final release / Expected release date

Normally the last release candidate that was issued without any show-stopper bugs.

Bug fix releases

No software is perfect. Once a sufficient large or critical number of bugs have been found for a certain release, the release manager releases a new bug fix release a.k.a. third-dot release (for example 2.1.2).

Enhancing Plone

Work out the idea

If you have any idea on how to make Plone even better as it is today, you should first talk with other people about your ideas. Both the IRC channel and the developers mailing list are good starting points for this. Talking to people about it will give you some pointers about the feasibility of the feature, and give you a good starting point for further work.

If your change or improvement is a big one, then you'll be asked to write a PLIP - Plone Improvement Proposal. In the PLIP you'll explain exactly what it is you want to do, how to do it and how it will integrate. To add a PLIP, you need to be on the development team, so you can add it as an Improvement Proposal in the Plone Roadmap area.

When writing a PLIP, be as specific and to-the-point as you can. Remember your audience - to get support for your proposal, people will have to be able to read it! A good PLIP is sufficiently clear for a knowlegable Plone user to be able to understand the proposed changes, and sufficiently detailed for the release manager and other developers to understand the full impact the proposal would have on the codebase. You don't have to list every line of code that needs to be changed, but you should also give an indication that you have some idea that how the change can be feasibly implemented.

If your change is minor then a ticket in the tracker will be sufficient, added as an enhancement. The key point here is that each change needs documentation so other users can see what it is. This can be in the form of an issue tracker entry, or a PLIP in the case of a bigger change. A bug or minor change does normally not need to go through a review process - a PLIP does.

When you've done your PLIP and you're happy with it, announce it on the developers mailing list. People will come and read the proposal and give feedback (hopefully positive).

At this point there is one key decision made by the developers:

• your PLIP will be adopted into Plone
• your PLIP will not be adopted

The latter isn't bad, it's just that this is not appropriate to be in the Plone core and have all the Plone team support. Each PLIP that gets accepted places a burden on the team, so people are selective in this process. There are many great products Plone uses that aren't directly part of Plone.

Start working on it

You can start the development at any time - but if you are going to modify Plone itself, you might want to wait to see if your idea is approved first to save yourself some work if it isn't. Your code has to be in an open accessible code versioning repository and you have to make a release bundle which allows the framework team to easily review your work. Please signify the release bundle on your PLIP. For a technical explanation see the "Using bundles for code review" paragraph of the "Version Control" page of this reference manual.

Once you've done developing it let the framework team know. At this point we'll do some things:

• review it and check you've done what you said
• see which release it will be accepted into

These are the criterias by which the framework team will review your review bundle:

1. Does the PLIP itself need work?
   • i.e. is this idea well baked and expressed clearly
2. Does the work proposed belong in Plone now, in the future?
   • Does it do the needful for Plone?
   • Is it more appropriate as a qualified add-on?
3. What condition is the review bundle in:
   • tests
   • sane implementation
   • clearly coded
   • uses current idioms of development
   • documentation / doc-tests

Note that if you don't finish your implementation in time for the feature freeze, it will not be included in the next Plone release. You can always submit your PLIP for the next release.

Finishing your work

Once you have finished your work and it was accepted by the framework team and the release manager, you will be asked to merge your work into the main development line. Merging the PLIP in is not the hardest part, but you must think about it when you develop. You'll have to interact with a large number of people to get it all set up. The merge may cause problems with other PLIP's coming in. During the merge phase you must be prepared to help out with all the features and bugs that arise.

If all went as planned the next Plone release will carry on with your PLIP in it. You'll be expected to help out with that feature after it's been released within reason, and we look forward to the next feature.

Overview

Part of our development process are some special events that are organized from time to time. The main idea behind these is to get people together to work on Plone at the same time, both as it is more efficient as you can get immediate feedback and as it is certainly more fun to work with others.

What is a Bug Day?

From time to time, especially in the weeks leading up to a release, the Plone Community arranges so-called "Bug Days". These days focus on identifying and fixing bugs and other issues with the Plone core, and is an excellent chance to get to know both Plone and its developers better. We therefor get together on IRC and collectively fix a selected set of bugs.

The Bug-Wrangler is the person who determines what bugs needs to be fixed and prioritizes as well as allocates bugs to each individual developer. Bug Day's happen in many other open source projects. Anyone can participate in a bug day; general users who are comfortable with using Subversion can test that a developer has fixed a bug or that the user can not provoke the bug in a different manner. And no matter what your current skill level is - from totally new to Plone to experienced Plone developer - you can make a difference!

Bug days are a critical development and social event that brings the developers closer through producively exorcising software of evil bugs. Bug days are usually announced on the developer mailing list and on the frontpage of plone.org.

What is a Sprint?

Tres Seaver originally came up with this idea. While a bug day lasts only one day or a weekend and people usually meet online, a Sprint typically lasts for several days to a full week and people meet in person. The idea of a Sprint is for a group of people to enhance, create, or fix one or more pieces of infrastructure. Usually they are focused on a specific set of topics instead of the entire product line.

Sprints are either funded by organizations or individuals who need specific features or are interested in working on some. Sprints happen yearly in the Plone community from sunny San Francisco to the top of mountains in the Alps where the only electricity is produced by a generator and a satellite uplink is used for internet connectivity. Sprints are extremly productive cultural events in the world of Plone. You can have a look at the list of past and upcoming Sprints.

What is a Symposium/Conference?

This is not a special kind of event for Plone or the open source world, but exactly what happens in other businesses as well. Usually there is one official Plone conference per year and at least one regional Symosium. Most of the time there is a business and a development orientated track each consisting of a series of talks and tutorials. See the events section for past and upcoming events.

Zope 3 is the new, cooler, faster, sexier version of Zope. Unfortunately, there is no direct migration path from Zope 2 to Zope 3. However, we are beginning to use Zope 3 technologies in Plone, alongside the Zope 2 core.

Zope 3 is a fairly different way of programming. It is based on the principle of components, that expose their functionality through well-defined interfaces. Whereas in Zope 2, you would need to mix classes into the inheritance hierarchy to gain certain functionality, for example by mixing in CopySupport to get cut/copy/paste support, Zope 3 uses the principle of adapters.

An adapter is simply a piece of glue code that can adapt an object to a given interface, so that the original object itself doesn't need to know anything about that interface or what it does. This makes it easier to re-use other Python objects that are not Zope aware, and makes components smaller, more precisely defined and thus easier to re-use.

Other types of Zope 3 components include utilities - stateless, global objects that can be looked up through a generic registry, and views, a special type of adapter that is typically used to contain the logic of page templates in a way that is more performant and easier to test.

Porting Plone wholesale to Zope 3 would essentially involve a re-write, and would break every installation, third party product and customisation out there. It is simply not an option. However, because Zope 3 is built out of small, re-usable components, we can use certain Zope 3 technologies today. Starting with Zope 2.8, the whole of Zope 3 ships as an add-on library and is available to use for Zope 2 applications like Plone. Over time, more and more parts of Zope 2 will get re-written to use Zope 3 technologies. This is accomplished via a product called Five (what's Zope 2 + 3?) that performs some magic to make the fundamental Zope 3 building blocks usable in Zope 2.

Zope 3 integration begun with the Plone 2.5 release cycle, and will continue gradually over time. That means that developers will have to start learning Zope 3 concepts. At the moment, there is still some overlap between what can be done with "old" techniques and what can be done in Zope 3. There are also dependencies on what happens in CMF and Zope 2 in general before certain things become available.

However, the basic mantra starting with Plone 2.5 is:

• New components should use Zope 3 technologies whenever possible and appropriate
• Any re-factoring of existing code should use Zope 3 technologies where possible and appropriate

This means that page templates with complex logic should use views. Any new component should make proper use of interfaces and adapters, and existing components should get interfaces and use adapters if at all possible.

It is important to realise that this is a gradual process, and there are many pragmatic decisions to be made. In general, you should always consult the developer list, the release manager or other members of the development team on non-trivial design decisions.

You can learn more about Zope 3 from one of the published books, from Philipp von Weitershausen's WorldCookery web site, from this tutorial or from the rest of documentation area.

This guide may not (and probably will not) give you all the details you need in order to resolve any confusion about Plone's internals. Luckily, there are several other places you can go.

• The rest of the documentation should be your first point of call.
• The Plone Developer list is a prime source of help. Please only post to this list with topics regarding the development of Plone itself, not third-party product development or customisation.
• Similarly, the #plone IRC chatroom is where most real-time discussion about Plone takes place. People with operator status are typically Plone developers.
• If you are contributing to Plone, you should make a point to both read the developer list regularly, and be online in #plone whenever you can, especially while you are working on Plone.