Changes between Version 64 and Version 65 of PLATFORM_STANDARDS_GENERAL
- Timestamp:
- 01/26/09 12:03:11 (16 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
PLATFORM_STANDARDS_GENERAL
v64 v65 5 5 6 6 = General Platform Standards = 7 This document contains information about the general standards for analysing, designing implementing and testing the diffferent kinds of tasks.7 This document contains information about the general standards for analysing, designing, implementing and testing the diffferent kinds of tasks. For specific requirements for a given phase, follow the links in the [wiki:PLATFORM_STANDARDS_GENERAL#Otherstandards] section 8 8 9 9 == Tasks kinds == 10 Currently we have five task kinds, each with different requirements for what should be done in each of the four phases - analysis, design implementation and testing. Note that the examples given are created according to the old standards and do not fully reflect the new ones. Some tasks may belong to several categories.10 Currently we have five task kinds, each with different requirements for what should be done in each of the four phases - analysis, design, implementation and testing. Note that the examples given are created according to the old standards and do not fully reflect the new ones. Some tasks may belong to several of the categories below. 11 11 12 12 === Coding task === … … 14 14 * [wiki:PLATFORM_STANDARDS_ANALYSIS Analysis] - contains a brief overview of the task and information about the required functionality, the expected results, ideas for implementation and demonstration as well as links to related tasks. 15 15 * [wiki:PLATFORM_STANDARDS_DESIGN Design] - describes the technologies that will be used for reaching the task's requirements. It should contain initial tests, libraries needed, rough algorithm explanation, class diagrams, etc. 16 * Implementation - describes what has been done. There should be a link to the changeset of the commit(s) where the modifications were done. Explanation of the changes should be provided. Write down the added functionality or improvements that the new code bring to the project. Explain which part of source you've added/edited and how, link the classes/packages/modules that you have created/modified. 16 * Implementation - describes what has been done. The following things are required: 17 * a link to the changeset of the commit(s) where the modifications were done 18 * explanation of the changes made (improvements, added functionality, etc.) 19 * links to any new classes/packages/modules created 20 * links to any new auto tests added 17 21 * Testing - includes writing user documentation, release documentation (where applicable), manual test cases in [http://sophie2.org/testlink Testlink], executing test cases and reporting bugs. 18 22 … … 20 24 * '''External feature (visible from the user):''' 21 25 * Analysis should include a specification (a draft of a specification diagram is recommended). 22 * Design should provide a manual testing scenario and inital auto tests. If the code exists, the design should state what is to be added/changed. When adding a new library feature, use test cases should be provided. It is recommended that you write some demos and an outline of your design. 26 * Design should provide: 27 * a manual testing scenario and/or inital auto tests/demos 28 * if the code exists - a description of what is to be added/changed 23 29 * Implementation should follow the design and make sure all features work and all tests pass. During the process more tests should be added where needed. 30 * Testing does not have any specific requirements for this kind of task. 24 31 * Example - [wiki:PRO_LIB_INSPECTOR_R0] 25 32 * '''Researching a technology or library''' … … 27 34 * Design should do the actual research. You can experiment with things but you should not pollute the main source - use the new libraries in a copy of the project or in another branch. 28 35 * Implementation should present the written results/conclusions of your reseach, demo code, tutorials and how-tos, etc. 36 * Testing should make sure the library is usable and suits our needs. 29 37 * Example - [wiki:S2S_DEPLOY_TECHNOLOGIES_R0] 30 38 * '''Internal feature (not directly visible)''' 31 39 * Analysis should state what the new feature should provide. 32 * Design should include use case tests, samples, demos and a design outline.40 * Design does not have any specifics related to this kind of task. 33 41 * Implementation should follow the design, make sure the required functionality is achieved and add tests where needed. 42 * Testing does not have any specific requirements for this kind of task. 34 43 * Example - [wiki:BASE_PERSISTENCE_COMMONS_R0] 35 44 * '''Structure changes (refactoring)''' … … 37 46 * Design should explain the changes to be made and how the problems can be fixed. 38 47 * Implementation should to the actual refactoring and describe the changes made. 48 * Testing should make sure the changes do no break the old code. 39 49 * Example - [wiki:PRO_LIB_CORE_COMMONS_R1] 40 50 41 51 === Bug Fix === 42 Bug fixes are unplanned tasks. They represent different kinds of unwanted application behavior - lack of functionality, misfunctionality, errors, etc. Bug tasks should be presented in the trac as "BUG_TASK_NAME". They do not have the usual workflow and do not go through the four phases like the other tasks. The workflow for the bug fixes is still not clear and will be described later. 52 Bug fixes are unplanned tasks. They represent different kinds of unwanted application behavior - lack of functionality, misfunctionality, errors, etc. Bug tasks should be presented in the trac as "BUG_TASK_NAME". Their phases are the same as other tasks but differ in meaning. The analysis is a thourough description of the bug and is written when the bug is reported. There is no testing phase for bug fixes - the implementation reviewer should make sure the bug is fixed. Here is a brief explanation about the requirements of each phase: 53 * [wiki:PLATFORM_STANDARDS_ANALYSIS Analysis] - contains a detailed description of the bug. 54 * [wiki:PLATFORM_STANDARDS_DESIGN Design] - suggests ideas for fixing the bug. 55 * Implementation - does the actual fixing and describes it. 56 * Testing - currently there is no testing phase for bug fixing tasks. 43 57 44 58 === Document === 45 Document tasks require the creation/improvement of different documents. In most cases, these documents are auxiliary for other tasks. The most common type of document we use is a wiki page but the result may also be a google doc or something else. The content of the documents varies and may include text, diagrams, media files, spreadsheets, etc. 59 Document tasks require the creation/improvement of different documents. In most cases, these documents are auxiliary for other tasks. The most common type of document we use is a wiki page but the result may also be a google doc or something else. The content of the documents varies and may include text, diagrams, media files, spreadsheets, etc. There is no testing phase for document tasks. Instead, the implementation reviewer should make sure the document is written as expected. Here are the requirements for the different sections: 46 60 * [wiki:PLATFORM_STANDARDS_ANALYSIS Analysis] - contains document requirements (type, structure and contents of the document). 47 * [wiki:PLATFORM_STANDARDS_DESIGN Design] - provides an outline of the document with the section that it contains and a description of each section's content.61 * [wiki:PLATFORM_STANDARDS_DESIGN Design] - provides an outline of the document with the sections that it contains and a description of each section's content. 48 62 * Implementation - contains link to the document(s) and a brief overview. Explanation of things added/changed should be provided. 49 63 * Testing - currently there is no testing phase for the document tasks. … … 51 65 52 66 === Setup === 53 The result of these tasks is hardware/software setup of different computer appliances that will be used for executing other tasks. These include website, wiki, developer platform setup, etc. 67 The result of these tasks is hardware/software setup of different computer appliances that will be used for executing other tasks. These include website, wiki, developer platform setup, etc. There is no testing phase for setup tasks. Instead, the implementation reviewer should make sure the setup is done well. Here are the requirements for the different sections: 54 68 * [wiki:PLATFORM_STANDARDS_ANALYSIS Analysis] - states what the requirements for this appliance are - both hardware and software. For example, some of the community server hardware requirements are hard disk space and bandwidth, and the software ones - a running web server, security issues, etc. 55 69 * [wiki:PLATFORM_STANDARDS_DESIGN Design] - describes which computer appliance will satisfy the requirements, how it will be set up, what technologies will be used. … … 59 73 60 74 === Maintenance === 61 Maintenance tasks should keep servers, important documents, code, etc. in a perfect working condition. These taskshave revisions on every iteration. 75 Maintenance tasks should keep servers, important documents, code, etc. in a perfect working condition. These taskshave revisions on every iteration. There is no testing phase for maintenance tasks. Instead, the implementation reviewer should make sure the maintenance is performed well. Here are the requirements for the different sections: 62 76 * [wiki:PLATFORM_STANDARDS_ANALYSIS Analysis] - covers current issues of the server/document/code and suggestions for improving. Should also contain a list of trivial actions that have to be done in every revision. 63 77 * [wiki:PLATFORM_STANDARDS_DESIGN Design] - explains what should be done for meeting the requirements, links to tools that will be used, algorithms, diagrams and whatever is needed for an easy implementation. … … 66 80 * Example - [wiki:INTERNAL_BACKLOG_MAINTENANCE_R2] 67 81 68 = Task results = 69 The results of the tasks should be described in the Implementation section of the task's page. Depending on the task kind, results can be: 70 * Documents (wiki pages, googledocs, etc.) 82 == Task results == 83 The results of the tasks should be described in the Implementation section of the task's page. Depending on the task kind, results can include (but are not limeted to): 71 84 * Source code (with unit tests) 72 85 * Diagrams (or design section of the same tasks) 86 * Documents (wiki pages, googledocs, etc.) 73 87 In the Task Result section of the analysis the expected results should be described. In the implementation section they should be linked. In different revisions same results can be linked, but the changes made in the current revision should be described. 74 88 75 = Reviewing=89 == Reviewing == 76 90 77 == Requirements==91 === Requirements === 78 92 Here are the requirements for each of the phases (in general). For specific requirements, see the other standards pages linked below. 79 * Analysis 80 * all the sections of the Analysis templates filled (with no fake information) 81 * Design 82 * for coding tasks: 83 * unit tests 84 * diagram(s) 85 * for document tasks: 86 * outline of the document's structure 87 * Implementation 88 * description of the changes made 89 * for coding tasks - links to the corresponding changesets 93 * Analysis - all the sections of the Analysis templates should be filled (with no fake information) according to the [wiki:PLATFORM_STANDARDS_ANALYSIS] page. 94 * Design - all the requirements listed in the [wiki:PLATFORM_STANDARDS_DESIGN] page should be met. 95 * Implementation - all the requirements listed in the above sections of this page should be met. 96 * Testing - all of the requirements in the [wiki:PLATFORM_STANDARDS_AUTO_TESTS] and [wiki:PLATFORM_STANDARDS_MANUAL_TESTS] should be met. 90 97 91 == Scoring==92 Here are general guidelines for what score a given task should get. Specific guidelines for the separate phases can be found in the the other documents (linked below).98 === Scoring === 99 Reviewers should either follow the standards in this document or comment them in the Comments section of this page. If you state a task does not comply with the standards, point to the requirements that are not met. Scores are in the range 1-5. Here are general guidelines for what score a given task should get. Specific guidelines for the separate phases can be found in the the other documents (linked below). 93 100 * Score 1 - the phase reviewed does not comply to the standards in the current document or the other standards documents. 94 101 * Score 2 - the phase reviewed complies with the standards to the most part but has some things missing and/or is unclear and/or might be misleading to the designer/interpreter. … … 97 104 * Score 5 - the phase reviewed complies with the standards and is clear, well-structured and sufficient and there is nothing more to be added - even a person that is not deep into the project can understand it. 98 105 99 = Other standards = 106 All reviews should be motivated. A detailed comment about why a task phase fails is required. For a score of 3 a list of things that have to be improved/added should be provided. Comments are encouraged for higher scores as well. Non-integer scores are STRONGLY disencouraged. If you give a task a score of 3.5, then you probably have not reviewed it thoroughly enough and cannot clearly state whether it is good or not. Once a given phase has been reviewed, it cannot be altered. If you think it is wrong, you should request a super review. Currently all super reviews should be discussed with Milo. Make sure you are able to provide clear arguments of what is wrong before you request a super review. 107 108 == Other standards == 100 109 This document provides only general rules. For specific ones, take a look at:[[BR]] 101 110 [wiki:PLATFORM_STANDARDS_ANALYSIS][[BR]] … … 105 114 [wiki:PLATFORM_STANDARDS_MANUAL_TESTS][[BR]] 106 115 107 = Naming conventions for wiki pages=116 == Naming conventions for wiki pages == 108 117 When creating a new wiki page, comply with the following conventions: 109 118 * Pages for tasks are written in UPPER_CASE (as the task id). Example: PLATFORM_NFR_USABILITY_R0.
