Author: Derick Rethans Date: 2007-01-10 15:28:42 +0100 (Wed, 10 Jan 2007) New Revision: 4483
Log: - Moved the file to a better location - Updated the process with points from our QA discussion. Added: docs/dev_process.txt Removed: docs/guidelines/dev_process.txt Copied: docs/dev_process.txt (from rev 4468, docs/guidelines/dev_process.txt) =================================================================== --- docs/guidelines/dev_process.txt 2007-01-04 21:49:18 UTC (rev 4468) +++ docs/dev_process.txt 2007-01-10 14:28:42 UTC (rev 4483) @@ -0,0 +1,279 @@ +=================== +Development Process +=================== + +.. contents:: Table of Contents + +Introduction +============ + +In order to stream line 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. + +Our development process consists of a set of eight 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 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. + +The Eight Steps +=============== + +1. `Present the Idea`_. +2. `Write Requirements Document`_. +3. Write `Design Specifications`_. +4. `Implementation`_. +5. `Activation`_. +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` +~~~~~~~~~~~~~~~~~~~~~~ + +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 +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 +library. + +__ `Bugs`_ + +While introducing a new component the following information should be present: + +- What is the component (or feature) about? +- Which features will it provide? +- A rationale why it should be part of the components. + +Those three elements will be checked against our policies of what components we +are interested it. *This document does not yet exist.* + +.. _`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. + +The Requirements document are most likely going to attract feedback as well. +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`_. + +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. + +.. _`Requirements Document`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/requirements_doc.txt + +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`_. + +.. _`Design Specification`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/design_doc.txt + +4. _`Implementation` +~~~~~~~~~~~~~~~~~~~~ + +In the implementation step the feature is implemented according to the Design +Specifications. There are several sub-items in this step: + +4.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 +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 done with the `phpDocumentor`_ syntax. A `small introduction`_ on how to +use it for the components is available as well. + +.. _`experimental`: http://svn.ez.no/svn/ezcomponents/experimental/ +.. _`phpDocumentor`: http://phpdoc.org +.. _`small introduction`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/source_documentation.txt + +4.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 +`````````````````````` + +There are many guidelines for implementing classes and methods. Please refer to +the `guidelines`_. + +.. _`guidelines`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/implementation.txt + +4.4. _`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 implemention should be matched against +the requirements specification and design document. On top of there a few extra +thing should be taken care of, which are described in the `review`_ document. + +.. _`review`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/review.txt + + +5. _`Activation` +~~~~~~~~~~~~~~~~ + +*We don't have this one* + +6. _`Testing` +~~~~~~~~~~~~~ + +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. + +Before we can do the release, we run a couple of scripts that validate a few +basic things: + +- whether we have uncommitted changes +- whether all tests pass +- whether line endings are correct +- whether the ChangeLog parses correctly as reST file +- code style guidelines are checked with a script + +7. _`Release` +~~~~~~~~~~~~~ + +A document that describes how to make releases of the eZ Components can be +found in svn__. + +__ http://svn.ez.no/svn/ezcomponents/docs/releasing.txt + +8. _`Maintenance` +~~~~~~~~~~~~~~~~~ + +*I have no idea what this should entail* + +Applicibility +------------- + +New Components +~~~~~~~~~~~~~~ + +Should follow all of `The Eight 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 this specific component. 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). + +From the `The Eight 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. + + +Feature Requests +~~~~~~~~~~~~~~~~ + +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. + + +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. + + +Glossary +======== + +maintainer +---------- + A person from the eZ 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`_. + +.. _`tutorial`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/tutorial.txt +.. _`issue tracker`: http://issues.ez.no + +.. + Local Variables: + mode: rst + fill-column: 79 + End: + vim: et syn=rst tw=79 Deleted: docs/guidelines/dev_process.txt =================================================================== --- docs/guidelines/dev_process.txt 2007-01-10 14:28:12 UTC (rev 4482) +++ docs/guidelines/dev_process.txt 2007-01-10 14:28:42 UTC (rev 4483) @@ -1,172 +0,0 @@ -=================== -Development Process -=================== - -.. contents:: Table of Contents - -Contributions -============= - -New Components --------------- - -Always follow the 5 phase development process: - -1. `Write Requirements document and Design specifications`_. -2. `Write API stubs with parameter documentation and descriptions`_. -3. `Write test cases`_. -4. `Implement classes`_. -5. Write extra documentation and `tutorial`_. - -The specs are stored in SVN -(http://svn.ez.no/svn/ezcomponents/packages/<component>/trunk/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`_. - -Write Requirements document and Design specifications -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before the requirements documents and design specifications are written an -idea for a new component should be announced on the `components mailinglist`_. -This is to make sure that only components 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 -library. - -While introducing a new component the following information should be present: - -- What is the component about? -- Which features will it provide? -- A rationale why it should be part of the components. - -After the component has been announced, discussed and approved it is time -to start writing the Requirements document and Design specifications. 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. - -The Requirements document and Design specifications are most likely going -to attract feedback as well. 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`_ -and `Design specifications`_. - -.. _`components mailinglist`: http://lists.ez.no/mailman/listinfo/components -.. _`Requirements document`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/requirements_doc.txt -.. _`Design specifications`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/design_doc.txt - -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 protyping -and ofcourse 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 mailinglist`_ to ask for feedback. Documentation of classes -is done with the `phpDocumentor`_ syntax. A `small introduction`_ on how to -use it for the components is available as well. - -.. _`experimental`: http://svn.ez.no/svn/ezcomponents/experimental/ -.. _`phpDocumentor`: http://phpdoc.org -.. _`small introduction`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/source_documentation.txt - -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 - -Implement classes -~~~~~~~~~~~~~~~~~ - -There are many guidelines for implementing classes and methods. Please refer to -the `guidelines`_. - -.. _`guidelines`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/ - - -Bugs ----- - -For tracking of bugs they should always be reporting in the bugsystem. 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). This allows easier -tracking of issues. While committing a bug fix the bugnumber 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 -be attached to the bugreport and when updates of the patch are requested -through the bug system the non-`maintainer`_ should update his patch there. -All patches for bugreports have to include test cases that show that before the -fix the bug failed, and afterwards it was fixed. Ofcourse a bug fix should not -break other tests (unless they were incorrect ofcourse). - - -Additions / Feature Requests ----------------------------- - -Should just like bugs always be filed into the bug system, 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 bug system. Once the spec is approved by one or more of the -current `maintainers`_, 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 -mailinglist. - - -Justifications -============== - -The process outlined above solves the basic requirement of acception -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 atleast 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. - - -Glossary -======== - -maintainer ----------- - A person from the eZ 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`_. - -.. _`tutorial`: http://svn.ez.no/svn/ezcomponents/docs/guidelines/tutorial.txt - -.. - Local Variables: - mode: rst - fill-column: 79 - End: - vim: et syn=rst tw=79 -- svn-components mailing list svn-components@lists.ez.no http://lists.ez.no/mailman/listinfo/svn-components
