Author: Derick Rethans Date: 2007-01-12 14:10:55 +0100 (Fri, 12 Jan 2007) New Revision: 4496
Log: - Update after meeting. Modified: docs/dev_process.txt Modified: docs/dev_process.txt =================================================================== --- docs/dev_process.txt 2007-01-12 12:26:38 UTC (rev 4495) +++ docs/dev_process.txt 2007-01-12 13:10:55 UTC (rev 4496) @@ -16,74 +16,93 @@ the finalization of each step. Depending on the situation not all eight 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. +adhere to those documents). -The Eight Steps +The Seven Steps =============== 1. `Present the Idea`_. 2. `Write Requirements Document`_. 3. Write `Design Specifications`_. -4. `Implementation`_. -5. `Activation`_. +4. `Time and Cost Estimates`_. +5. `Implementation`_. 6. `Testing`_. 7. `Release`_. -8. `Maintenance`_. -The specs are stored in SVN -(http://svn.ez.no/svn/ezcomponents/trunk/<component>/design). And a -review of the component is done after step 1 (general review), step 2 -(consistency with other components) and step 4 (test cases, consistency, CS and -other guidelines). -The full development is done in SVN and new components can only be added by -`maintainers`_. - 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* component should be announced on the `components mailing list`_. -`Feature requests`_ and `bug reports`__ should go to the `issue tracker`_. -This is to make sure that only components are developed which fit into +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 component part of the eZ components +whether we are interested in making a new feature part of the eZ components library. -__ `Bugs`_ +1.2. Enhancement +```````````````` -While introducing a new component the following information should be present: +Feature requests should go to the `issue tracker`_. -- What is the component (or feature) about? +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: + +- What is the feature about? - Which features will it provide? -- A rationale why it should be part of the components. +- A rationale why it should be part of the product. -Those three elements will be checked against our policies of what components we +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. + .. _`components mailing list`: http://lists.ez.no/mailman/listinfo/components + 2. _`Write Requirements Document` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -After the component 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 where the documents can be stored while -waiting for feedback. At this same time *some* prototyping can be done as well -there. +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. -The Requirements document are most likely going to attract feedback as well. +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. -There is also more information on how to structure the `Requirements -Document`_. +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. @@ -93,48 +112,82 @@ 3. _`Design specifications` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Design Specification describe how the feature is going to be implemented with the Requirements Document in mind. -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 as -`Design Specification`_. +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. + .. _`Design Specification`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/design_doc.txt -4. _`Implementation` + +4. _`Time and Cost Estimates` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +5. _`Implementation` ~~~~~~~~~~~~~~~~~~~~ -In the implementation step the feature is implemented according to the Design -Specifications. There are several sub-items in this step: +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: -4.1. _`Write API stubs with parameter documentation and descriptions` +5.1. _`Write API stubs with parameter documentation and descriptions` ````````````````````````````````````````````````````````````````````` -This should serve as some prototyping to see how the code could work. As part -of the API stubs you can already create the files with the classes and methods -that you think your API needs. Often this will result from some prototyping -and of course the design document. To complete this phase there should +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. After the API stubs are written and committed -to SVN (still in the `experimental`_ directory) a mail should be send to -the `components mailing list`_ to ask for feedback. Documentation of classes +is written during this phase. Documentation of classes is done with the `phpDocumentor`_ syntax. A `small introduction`_ on how to -use it for the components is available as well. +use it for the eZ 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. + .. _`experimental`: http://svn.ez.no/svn/ezcomponents/experimental/ +.. _`trunk`: http://svn.ez.no/svn/ezcomponents/trunk/ .. _`phpDocumentor`: http://phpdoc.org -.. _`small introduction`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/source_documentation.txt +.. _`small introduction`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/implementation.txt -4.2. Write test cases +5.2. Write test cases ````````````````````` Test cases are written for PHPUnit, see the documentation on how to `set-up the test environment`_. .. _`set-up the test environment`: http://svn.ez.no/svn/ezcomponents/docs/test_environment.txt -4.3. Implement classes +5.3. Implement classes `````````````````````` There are many guidelines for implementing classes and methods. Please refer to @@ -142,7 +195,7 @@ .. _`guidelines`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/implementation.txt -4.4. _`Implementation Review` +5.4. _`Implementation Review` ````````````````````````````` After the implementation of the classes there is a review required of the @@ -154,19 +207,24 @@ .. _`review`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/review.txt +Transition +`````````` -5. _`Activation` -~~~~~~~~~~~~~~~~ +Once the implementation has been reviewed and all the comments of the reviewers +have been integrated into the implementation the next step can be started. -*We don't have this one* 6. _`Testing` ~~~~~~~~~~~~~ -In the testing phase we run all the eZ component tests as one big bunch, using +In the testing phase we run all the eZ Component 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. +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: @@ -184,18 +242,15 @@ __ http://svn.ez.no/svn/ezcomponents/docs/releasing.txt -8. _`Maintenance` -~~~~~~~~~~~~~~~~~ -*I have no idea what this should entail* Applicability ------------- -New Components -~~~~~~~~~~~~~~ +New Features +~~~~~~~~~~~~ -Should follow all of `The Eight Steps`_. +Should follow all of `The Seven Steps`_. Bugs @@ -208,34 +263,39 @@ 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 this specific component. The patch should +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). +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 Eight Steps`_, step 2 (`Write Requirements Document`_) and step 3 +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 4.1 (`Write API stubs with parameter -documentation and descriptions`_) and step 4.4 (`Implementation Review`_) are -also not required. +with either one of those documents. Step 5.1 (`Write API stubs with parameter +documentation and descriptions`_) and step 5.4 (`Implementation Review`_) are +also not required, although the latter might be a good idea to do for very +large fixes. -Feature Requests -~~~~~~~~~~~~~~~~ +.. _CLA: http://ez.no/ezpublish/contributing/cla +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 -components. When a FR 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 component he can be -marked as a `maintainer`_ for that specific component. Discussion about whether -new features or components are wanted are always required to be done on the -components mailing list. +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 -- svn-components mailing list svn-components@lists.ez.no http://lists.ez.no/mailman/listinfo/svn-components
