0027023: Documentation -- cross-references are hardly noticeable in PDF
[occt.git] / dox / dev_guides / contribution_workflow / contribution_workflow.md
ba06f8bb 1Contribution Workflow {#occt_dev_guides__contribution_workflow}
bf62b306 2====================================
5@section occt_contribution_workflow_1 Introduction
7The purpose of this document is to describe standard workflow for processing contributions to certified version of OCCT.
9@subsection occt_contribution_workflow_1_1 Use of issue tracker system
11Each contribution should have corresponding issue (bug, or feature, or integration request)
12registered in the MantisBT issue tracker system accessible by URL
14The issue is processed further according to the described workflow.
16@subsection occt_contribution_workflow_1_2 Access Levels
18 Access level defines the permissions of the user to view,
19 register and modify issues in a Mantis bugtracker.
20 The correspondence of access level and user permissions
21 is defined in accordance with the table below.
23| Access level | Granted to | Permissions | Can set statuses |
24|:------------- | :--------- | :-------------- | :----------------------- |
25| Viewer | Everyone (anonymous access) | View public issues only | No |
26| Reporter | Users registered on dev.opencascade.com | View, report, and comment issues | New, Resolved |
27| Updater | Users of dev.opencascade.com in publicly visible projects | View and comment issues | New, Resolved |
28| Developer | OCC developers and external contributors who signed the CLA | View, report, modify, and handle issues | New, Assigned, Resolved, Reviewed |
29| Tester | OCC engineer devoted to certification testing | View, report, modify, and handle issues | Assigned, Tested |
30| Manager | Person responsible for a project or OCCT component | View, report, modify, and handle issues | New, Resolved, Reviewed, Tested, Closed |
32According to his access level, the user can participate in the issue handling process under different roles, as described below.
34@section occt_contribution_workflow_2 Typical workflow for an issue
36@subsection occt_contribution_workflow_2_1 General scheme
38@image html OCCT_ContributionWorkflow_V3_image001.png "Standard life cycle of an issue"
39@image latex OCCT_ContributionWorkflow_V3_image001.png "Standard life cycle of an issue"
41@subsection occt_contribution_workflow_2_2 Issue registration
43An issue is registered in Mantis bugtracker by the Reporter with definition of the necessary attributes.
44The definition of the following attributes is obligatory:
46 * **Category** - indicates component of OCCT to which the issue relates. If in doubt, assign OCCT:Foundation Classes.
47 * **Reproducibility**
48 * **Severity**
49 * **Priority**
50 * **Profile** - allows defining the platform on which the problem was detected from the list of predefined platforms. If a platform is absent in the list of predefined platforms it is possible to use Or Fill In option to define the platform manually.
51 * **Platform**
52 * **OS**
53 * **OS Version**
54 * **Products Version** - defines the version of Open CASCADE on which the problem has been detected.
55 * **Summary** - a short, one sentence description of the issue. It has a limit of 128 characters. It should be informative and useful for the developers. It is advisable to avoid vague or misleading phrases, such as "it doesn't work" or "it crashed". It is not allowed to mention the issue originator, and in particular the customer, in the name of the registered issue.
f9e256b3 56 * **Description** - should contain a detailed definition of the nature of the registered issue depending on its type. For a bug it is required to submit a detailed description of the incorrect behavior, including the indication of the cause of the problem (if possible at this stage) or any inputs from the originator. For a feature or integration request it is recommended to describe the proposed feature in details (as much as possible at that stage), including the changes required for its implementation and the main features of the new functionality. Filling the bug description is obligatory.
58For example:
613rd-party library New_Image has been implemented in OCCT. This library provides build-in support of popular image processing formats, such as JPEG, PNG, GIF or BMP. It should replace all obsolete code for image load/dump in the future. Currently it is used to save images from Window / OpenGL context.
bf62b306 64 * **Steps To Reproduce** - in this field it is possible to describe in detail how to reproduce the issue. This field considerably helps to find the cause of the problem, to eliminate it and to create the test case.
f9e256b3 65 * **Additional information and documentation updates** - this field should be filled in case when it is specifically required to single out the changes to be considered when porting from the previous version of OCCT or when the corresponding GIT commit messages are missing or misleading.
66 * **Upload File** field allows attaching the shapes, scripts or modified source files of OCCT. It is recommended to attach a prototype test case in form of a Tcl script for DRAW, using either existing DRAW commands, or a C++ code which can be organized in DRAW commands, as well as sample shapes or other input data (if applicable), immediately after the issue registration.
bf62b306 67
68 The newly registered issue gets status **NEW** and is assigned to the developer responsible for the OCCT component indicated in the Category field (Maintainer).
70@subsection occt_contribution_workflow_2_3 Assigning the issue
72 The description of the new issue is checked by the **Maintainer** and if it is feasible,
73 he may assign the issue to a **Developer**. Alternatively, any user with **Developer** access level
74 or higher can assign the issue to himself if he wants to provide a solution.
76 The recommended way to handle contributions is that the **Reporter** assigns the issue to himself and provides a solution.
78 The **Maintainer, Technical Project Manager,** or **Bugmaster** can close or reassign the issue
79 (in **FEEDBACK** state) to the **Reporter** after it has been registered, if its description does not contain sufficient details to reproduce the bug or explain the purpose of the new feature.
80 That decision shall be documented in the comments to the issue in the Bugtracker.
82 The assigned issue should have state **ASSIGNED**.
84@subsection occt_contribution_workflow_2_4 Resolving the issue
86 The **Developer** responsible for the issue assigned to him provides a solution
87 as a change on the version of OCCT indicated in the issue attributes, or the last development version.
f9e256b3 89@subsubsection occt_contribution_workflow_2_4_1 Creation of the branch
91 The modification of sources should take place in the dedicated branch of the official OCCT Git repository.
93 The branch should be based on the recent version of the master branch (not later than the commit tagged as the last OCCT release).
95 The branch name should be composed of letters **CR** followed by the issue ID number (without leading zeros). It is possible to add an optional suffix to the branch name after the issue ID, e.g. to distinguish between several versions of the fix.
97 The name of the branch, where the fix is submitted, should be given in the note to the Mantis issue (providing the direct link to relevant branch view in GitWeb is encouraged).
99 Please, see the details in the @ref occt_dev_guides__git_guide "Guide to using GIT".
101@subsubsection occt_contribution_workflow_2_4_2 Requirements to the code modification.
103 The amount of code affected by the change should be limited
104 to the changes required for the bug fix or improvement.
bf62b306 105 Change of layout or re-formatting of the existing code is allowed
f9e256b3 106 only in the parts where meaningful changes related to the issue have been made.
108 Every developer providing a contribution to the source code of OCC should make the appropriate comments in the code to improve its legibility and maintainability.
110 Making the appropriate comments is mandatory in the following cases:
111 * Development of a new package / class / method / enumeration;
112 * Modification of an existing package / class / method / enumeration that changes its behavior;
113 * Modification / new development impacts other packages / classes / methods / enumerations, the documentation which of should be modified correspondingly.
115 The only case when the comments may be not required is
116 a modification that does not change the existing behavior in any noticeable way
117 or brings the behavior in accordance with the existing description.
119 The comments must be in good English, containing as much relevant
120 information and as clear as possible.
123@subsubsection occt_contribution_workflow_2_4_3 Requirements to the commit message.
125 The commit message posted in GIT constitutes an integral part of both the fix and the release documentation.
127 The first line of the first commit message should contain the Summary of the issue (starting with its ID followed by colon, e.g. "0022943: Bug TDataXtd_PatternStd").
129 The next lines should contain a mandatory description of changes. The contents and the recommended structure of the description depend on the nature of the bug.
131 In a general case, the following elements should be present:
132 * **Problem** – a description of the unwanted behavior;
133 * **Change** – a description of the implemented changes, including the name of class/method/enumeration that has been modified or implemented anew;
134 * **Result** – a description of the current behavior (after the implementation).
136For example:
139The exception in method BRepFill_Cone::Truncate caused by hard-coded number of symbols in the parameter for truncation operation has been fixed. Now the parameter provided by method BRepFill_Cone::Parameter is stored in a variable, which is used for truncation.
142 \note Please, note that such phrases as "the bug was fixed" or "the regression was eliminated" do not describe the fix, because they provide no information about the **Change**.
144Other cases may require a more detailed description, or vice versa, the Problem or the Result may not be worth indicating. It is not advisable to go too deep into implementation details, however, any reader should be able to understand, what has been fixed and where.
146Let us see some typical cases:
148#### Implementation of a new method:
151New method CheckFace::Point has been implemented to check if the point is IN the face.
154#### Improvement of an existing algorithm:
157The concatenation algorithm in class BSpline_Surface has been fixed to work with periodic Bspline surfaces.
160#### Removal of an obsolete method:
163Class BOPCol_Array1 has been removed. Instead, new method Ncollection_BaseVector::SetIncrement allows setting the size of increment dynamically. Classes from package BOPDS have been modified accordingly.
166#### Description of large-scale development
168The implementation of new functionalities or functional overhauls can contain numerous modifications concerning numerous packages or numerous classes in one package. The description of such implementation should include two elements:
169* General description or Summary;
170* List of modifications with necessary comments.
172According to the requirements of chapter @ref occt_contribution_workflow_2_2 "Issue Registration" in the present document, the purpose of an improvement should be already given in the Bug Description. However, if the Bug Description is missing or if it describes the problems rather then their solution or if some other important information is missing, it should be given in the commit or better, if there were many different commits, backtracking and overwriting each other, in **Additional information and documentation updates** field.
174Here is the example of information about numerous changes in connection with the bug that should be provided:
177The following modifications have been implemented to improve the stereoscopic output:
178 - The target FBO is passed as parameter in method *OpenGl_View::Render()*.
179 - Read/Write buffers management logic has been revised in class *OpenGl_Context* taking into account FBOs.
180 - New DRAWEXE command *dumpstereo* allows dumping the contents of 2D viewer.
181 - New methods *LProjection* and *RProjection* have been added in class Graphic3d_Camera::UpdateProjection() for off-screen rendering.
184For more examples of bug descriptions, please, refer to the previous versions of OCCT Release Notes.
186@subsubsection occt_contribution_workflow_2_4_4 Submitting the contributions
bf62b306 187
188 In some cases (if Git is not accessible for the contributor),
189 external contributions can be submitted as patch (diff) files or sources
190 attached to the Mantis issue, with indication of OCCT version on which the fix is made.
191 Such contributions should be put to Git for processing by someone else,
192 and hence they have less priority in processing than the ones submitted directly through Git.
f9e256b3 194 To submit the modified sources for review and testing, the issue, for which the solution is provided, should be switched to **RESOLVED** state and assigned to the developer who is expected to make a code review (the **Reviewer**; by default, can be set to the **Maintainer** of the component).
bf62b306 195
196@subsection occt_contribution_workflow_2_5 Code review
198 The **Reviewer** analyzes the proposed solution for applicability in accordance with OCCT Code reviewing rules and examines all changes in the sources to detect obvious and possible errors, misprints, conformity to coding style.
200 * If Reviewer detects some problems, he can either:
201 * Fix these issues and provide new solution, reassigning the issue (in **RESOLVED** state) to the **Developer**, who then becomes a **Reviewer**.
202 Possible disagreements should be resolved through discussion, which is done normally within issue notes (or on the OCCT developer’s forum if necessary).
203 * Reassign the issue back to the **Developer**, providing detailed list of remarks. The issue then gets status **ASSIGNED** and a new solution should be provided.
204 * If Reviewer does not detect any problems, he changes status to **REVIEWED**.
206@subsection occt_contribution_workflow_2_6 Testing
208 The issues that are in **REVIEWED** state are subject of certification (non-regression) testing.
209 The issue is assigned to OCC **Tester** when he starts processing it.
210 The results of tests are checked by the **Tester**:
211 * If the **Tester** detects build problems or regressions, he changes the status to **ASSIGNED** and reassigns the issue to the **Developer** with a detailed description of the problem. The **Developer** should produce a new solution.
212 * If the **Tester** does not detect build problems or regressions, he changes the status to **TESTED** for further integration.
214@subsection occt_contribution_workflow_2_7 Integration of a solution
216 Before integration into the master branch of the repository the **Integrator** checks the following conditions:
217 * the change has been reviewed;
218 * the change has been tested without regressions (or with regressions treated properly);
219 * the test case has been created for this issue (when applicable), and the change has been rechecked on this test case;
bf62b306 220 * the change does not conflict with other changes integrated previously.
222 If the result of check is successful the Integrator integrates solution
223 into the master branch of the repository. Each change is integrated into the master branch
224 as a single commit without preserving the history of changes made in the branch
225 (by rebase, squashing all intermediate commits), however, preserving the author when possible.
226 This is done to have the master branch history plain and clean.
227 The following picture illustrates the process:
dd21889e 229@image html OCCT_ContributionWorkflow_V3_image002.png "Integration of several branches"
230@image latex OCCT_ContributionWorkflow_V3_image002.png "Integration of several branches"
bf62b306 231
232 The new master branch is tested against possible regressions that might appear due to interference between separate changes. When the tests are Ok, the new master is pushed to the official repository
233 and the original branches are removed from it.
234 The issue status is set then to **VERIFIED** and is assigned to the **Reporter** so that he could check the fix as-integrated.
236@subsection occt_contribution_workflow_2_8 Closing a bug
238 The **Bugmaster** closes the issue after regular OCCT Release provided that the issue status is **VERIFIED** and that issue was really solved in that release, by rechecking the corresponding test case. The final issue state is **CLOSED**.
240@subsection occt_contribution_workflow_2_9 Reopening a bug
242 If a regression is detected, the **Bugmaster** may reopen and reassign the **CLOSED** issue to the appropriate developer with comprehensive comments about the reason of reopening. The issue then becomes **ASSIGNED** again.
f9e256b3 244@section occt_contribution_workflow_3 Issue attributes
bf62b306 245
f9e256b3 246@subsection occt_contribution_workflow_3_1 Severity
bf62b306 247
248 Severity shows at which extent the issue affects the product.
249 The list of used severities is given in the table below in the descending order.
251 | Severity | Description | Weight for Bug Score |
252 | :---------- | :------------------------------------------------ | :------------------: |
253 | crash | Crash of the application or OS, loss of data | 5 |
254 | block | Regression corresponding to the previously delivered official version. Impossible operation of a function on any data with no work-around. Missing function previously requested in software requirements specification. Destroyed data. | 4 |
255 | major | Impossible operation of a function with existing work-around. Incorrect operation of a function on a particular dataset. Impossible operation of a function after intentional input of incorrect data. Incorrect behavior of a function after intentional input of incorrect data. | 3 |
256 | minor | Incorrect behavior of a function corresponding to the description in software requirements specification. Insufficient performance of a function. | 2 |
257 | tweak | Ergonomic inconvenience, need of light updates. | 1 |
258 | text | Inconsistence of program code to the Coding Standard. Errors in source text (e.g. unnecessary variable declarations, missing comments, grammatical errors in user manuals). | 1 |
259 | trivial | Cosmetic bugs. | 1 |
260 | feature | Bug fix, new feature, improvement that requires workload estimation and validation. | 1 |
261 | integration request | Requested integration of an existing feature into the product. | 0 |
262 | Just a question | A question to be processed, without need of any changes in the product. | 0 |
f9e256b3 264@subsection occt_contribution_workflow_3_2 Statuses of issues
bf62b306 265
266 The bug statuses that can be applied to the issues are listed in the table below.
268 | Status | Description |
269 | :------------------- | :----------------------------------------- |
270 | New | New just registered issue. Testing case should be created by Reporter. |
271 | Feedback | The issue requires more information; the original posters should pay attention. |
272 | Assigned | Assigned to a developer. |
273 | Resolved + a resolution | The issue has been fixed, and now is waiting for revision. |
274 |Revised + a resolution | The issue has been revised, and now is waiting for testing. |
275 | Tested | The fix has been internally tested by the tester with success on the full non-regression database or its part and a test case has been created for this issue. |
276 | Verified | The fix has been integrated into the master of the corresponding repository |
277 | Closed | The fix has been integrated to the master. The corresponding test case has been executed successfully. The issue is no longer reproduced. |
f9e256b3 279@subsection occt_contribution_workflow_3_3 Resolutions
bf62b306 280
281 **Resolution** is set when the bug is resolved. "Reopen" resolution is added automatically when the bug is reopened.
283 | Resolution | Description |
284 |:--------------------- | :--------------------------------------------------------------------------- |
285 | Open | The issue is being processed. |
286 | Fixed | The issue has been successfully fixed. |
287 | Reopened | The bug has been reopened because of insufficient fix or regression. |
8d44b0a0 288 | Unable to reproduce | The bug is not reproduced. |
bf62b306 289 | Not fixable | The bug cannot be fixed because it is a bug of third party software, or because it requires more workload than it can be allowed. |
290 | Duplicate | The bug for the same issue already exists in the tracker. |
291 | Not a bug | It is a normal behavior in accordance with the specification of the product |
292 | No change required | The issue didn’t require any change of the product, such as a question issue |
293 | Suspended | This resolution is set for Acknowledged status only. It means that the issue is waiting for fix until a special administrative decision is taken (e.g. a budget is not yet set in accordance with the contract) |
294 | Documentation updated | The issue was a normal behavior of the product, but the actions of the user were wrong. The specification and the user manual have been updated to reflect this issue. |
295 | Won’t fix | An administrative/contractual decision has been taken to not fix the bug |
bf62b306 297
bf62b306 298
bf62b306 299
f9e256b3 300