Zeta Components - high quality PHP components

Development Process

Table of Contents

Introduction

In order to streamline our development we have a specific set of guidelines that need to be followed. This document summarizes the steps and provides pointers to the relevant guidelines where that is relevant. This document is ultimately meant for the Zeta Components developers.

Our development process consists of a set of seven steps; transitions between the different states can be done when the criteria are matched that describe the finalization of each step. Depending on the situation not all seven steps are necessary (for example for bug fixes you don't need to write a Requirements Document or Design Specification as a bug is simply a feature that doesn't adhere to those documents).

The Seven Steps

  1. Present the Idea.

  2. Write Requirements Document.

  3. Write Design Specifications.

  4. Time and Cost Estimates.

  5. Implementation.

  6. Testing.

  7. Release.

Detailed Information about the Steps

1. Present the Idea
1.1. New Feature

Before the requirements documents and design specifications are written an idea for a new feature should be announced on the components mailing list. This is to make sure that only features are developed which fit into our global idea of "high quality components for web application development". Based on the ideas that are outlined on the list we will make a decision whether we are interested in making a new feature part of the Zeta Components library.

1.2. Enhancement

Feature requests should go to the issue tracker.

1.3. Bug

Bug reports should go to the issue tracker.

Transition

While introducing a new feature or an enhancement the following information should be present:

Those three elements will be checked against our policies of what features we are interested it. This document does not yet exist.

For bug reports the information in the issue tracker should be filled in.

2. Write Requirements Document

After a new feature or enhancement has been announced, discussed and approved it is time to start writing the requirements document. At this point we will create a directory in the experimental directory in SVN where the documents can be stored while waiting for feedback (http://svn.ez.no/svn/ezcomponents/experimental/<component>/design). At this same time some prototyping can be done as well there.

There is also more information on how to structure an requirements document.

Discussions

The requirements document is most likely going to attract feedback. This is supposed to be a creative and iterative process which means that proceeding to the next phase should not commence before the documents have been approved as well.

Discussions about the requirements should be done on the components mailing list.

Transition

When the Requirements Document contains all the required information, and it has been approved by the product manager, the next step can start where a Design Document is written.

3. Design specifications

At this point we assign a mentor to the component. This mentor makes sure all the necessary steps and reviews are done correctly and keeps an eye on the design, working closely with the developer that makes the design.

The design specification describes how the feature is going to be implemented with the requirements document in mind. The design specification is there to see whether something can be implemented, and also explores the different implementation approaches. The different approaches can then be assessed in the next step (Time and Cost Estimates).

Only after the design specification has been approved can be started with the implementation of the feature. There are guidelines on how to create such an design specification.

Discussions

The design specification is most likely going to attract feedback in the form of different implementation approaches or just general comments.

Discussions about the design should be done on the components mailing list, or where possible in face-to-face meetings with a summary to the mailing list.

Transition

The design specification is checked against the guidelines on how to write such a document. There is also an assessment whether the feature can be implemented at all. The design specification should be vetted by the product manager before the next step can be taken.

4. Time and Cost Estimates

Once the requirement specifications have been written and the design has been made, it is possible to estimate how much time the implementation of a specific item will take. During the two previous phases all possible ways of implementation are researched and there is knowledge about what the implementation of a new feature exactly will entail.

There are a couple of things that need to be taken into account, for example which part of the software is to be touched. Standalone small parts are easier to estimate then larger parts that touch many different corners of the software.

5. Implementation

In the implementation step the feature is implemented according to the design specifications. When this step is reached for a new feature, the appropriate directory structures can be moved from "experimental" to "trunk".

There are several sub-items in this step:

5.1. Write API stubs with parameter documentation and descriptions

This should serve as some prototyping to see how the design could work. As part of the API stubs you should already create the files with the classes and methods that you think your API needs, following the design that is outlined in the design document. To complete this phase there should be an example in the main classes` doc blocks and API documentation for each constant, variable, property and method. Of course during development some things might change. This first initial implementation of the stubs just serves as a little playground. It is important that no implementation code is written during this phase. Documentation of classes is done with the phpDocumentor syntax. A small introduction on how to use it for the Zeta Components is available as well.

Transition

After the API stubs are written and committed to SVN a mail should be send to the components mailing list to ask for feedback.

5.2. Write test cases

Test cases are written for PHPUnit, see the documentation on how to set-up the test environment.

5.3. Initial Implementation

There are many guidelines for implementing classes and methods. Please refer to the guidelines.

Transition

After the first implementation has been done, alpha1 is released.

5.4. Initial Implementation Review

After the implementation of the classes there is a review required of the implementation. The review should be done by at least two people that where not part in writing the code. The original author is of course free to do a review as well. During the review the implementation should be matched against the requirements specification and design document. On top of there a few extra things should be taken care of, which are described in the review document.

5.5. Updating Implementation according to review

After the Initial Implementation Review has been done, the original developer updates the implementation according to provided feedback. In case conflicting opinions exist the issues need to be discussed on the list, in all other cases it is suggested to discuss all found issues on the list as well.

Transition

Release a beta version of the component.

5.6. Implementation Review

The updated code is reviewed once again according to the review guidelines. If more issues arise go back to step 5.5.

Transition

Once the implementation has been reviewed and all the comments of the reviewers have been integrated into the implementation a Release Candidate can be released.

6. Testing

In the testing phase we run all the Zeta Components tests as one big bunch, using all the different permutations of parameters that we support. At the moment this is a multitude of PHP versions and supported Databases, but other input variables might be defined later as well.

Transition

Before we can do the release, we run a couple of scripts that validate a few basic things:

7. Release

A document that describes how to make releases of the Zeta Components can be found in svn.

Applicability

New Features

Should follow all of The Seven Steps.

Bugs

Bugs should should always be reported in the issue tracker. Bugs should also be reported here by ourselves if we are not in the first development cycle of a component (e.g. before version 1.0) or during an active development face for a new .y release. This allows easier tracking of issues. While committing a bug fix the bug number should be mentioned.

For bugs from non-maintainers that come with a patch, the patch should be reviewed by one of the maintainers of the specific area. The patch should be attached to the bug report and when updates of the patch are requested through the issue tracker the non-maintainer should update his patch there. All patches for bug reports have to include test cases that show that before the fix the bug failed, and afterwards it was fixed. Of course a bug fix should not break other tests (unless they were incorrect of course). A patch by a non-maintainer can only be committed when the CLA has been signed.

From the The Seven Steps, step 2 (Write Requirements Document) and step 3 (Write Design Specifications) can be omitted because a bug is in violation with either one of those documents. Step 5.1 (Write API stubs with parameter documentation and descriptions) and step 5.4/5.6 (Initial Implementation Review) are also not required, although the latter might be a good idea to do for very large fixes.

Enhancements

Should just like bugs always be filed into the issue tracker, also if it comes from maintainers. The development process is handled in the same way as new features. When an enhancement is filed, the specs of the feature/change are attached to the report in the issue tracker. Once the specification is approved by one or more of the current maintainers and the product manager, it can be moved into the requirements and design documents. The development can be done in SVN directly, but is not required to be done there for non-maintainers. Once a contributer has shown enough knowledge about a specific area he can be marked as a maintainer for that specific area. Discussion about whether enhancements are wanted are always required to be done on the components mailing list. We can only allow code coming from external contributers into the repository when the CLA has been signed.

Justifications

The process outlined above solves the basic requirement of accepting contributions while defining a clear process. The Components are self contained building blocks and therefore changes are often very small and contained. Because of this nature it is not required that every little issue is reviewed by at least one other person. By allowing direct commit access to SVN we allow quicker development while still maintaining quality (as every addition and bug fix is required to have a test case). Because the components have a quick release cycle we would hardly have conflicts between bug fixes and new features so we do not have to create many branches. A component would usually have one branch, or perhaps two concurrent ones if we go for a version 2 of a component. We are reluctant to bump the version number to 2 though as this would only be done on a backward compatibility breaking change.

Version States

pre-alpha
Development state, everything can change.
alpha 1
First release of a component up for initial review.
beta 1
First release of a component after the implementation of review comments. The API is still subject to change, but the general workings of the component should not change anymore.
beta n
Releases of a component after implementation of more reviews. The API is still allowed to change, but doing so is discouraged.
rc 1
Release candidate, the API can not change anymore unless there is an extremely compelling reason to do so.
final
The component is now released, BC can not be broken anymore.

Glossary

maintainer

A person from the Zeta Components development team or an external contributer that has shown enough knowledge about a specific component, or contributes a whole new component. Maintainers can commit directly to SVN.

maintainers

More than one maintainer.