![]() |
Open CASCADE Technology
6.9.1
|
The purpose of this document is to describe standard workflow for processing contributions to certified version of OCCT.
Each contribution should have corresponding issue (bug, or feature, or integration request) registered in the MantisBT issue tracker system accessible by URL http://tracker.dev.opencascade.org. The issue is processed further according to the described workflow.
Access level defines the permissions of the user to view, register and modify issues in a Mantis bugtracker. The correspondence of access level and user permissions is defined in accordance with the table below.
Access level | Granted to | Permissions | Can set statuses |
---|---|---|---|
Viewer | Everyone (anonymous access) | View public issues only | No |
Reporter | Users registered on dev.opencascade.com | View, report, and comment issues | New, Resolved |
Updater | Users of dev.opencascade.com in publicly visible projects | View and comment issues | New, Resolved |
Developer | OCC developers and external contributors who signed the CLA | View, report, modify, and handle issues | New, Assigned, Resolved, Reviewed |
Tester | OCC engineer devoted to certification testing | View, report, modify, and handle issues | Assigned, Tested |
Manager | Person responsible for a project or OCCT component | View, report, modify, and handle issues | New, Resolved, Reviewed, Tested, Closed |
According to his access level, the user can participate in the issue handling process under different roles, as described below.
An issue is registered in Mantis bugtracker by the Reporter with definition of the necessary attributes. The definition of the following attributes is obligatory:
The newly registered issue gets status NEW and is assigned to the developer responsible for the OCCT component indicated in the Category field (Maintainer).
The description of the new issue is checked by the Maintainer and if it is feasible, he may assign the issue to a Developer. Alternatively, any user with Developer access level or higher can assign the issue to himself if he wants to provide a solution.
The recommended way to handle contributions is that the Reporter assigns the issue to himself and provides a solution.
The Maintainer, Technical Project Manager, or Bugmaster can close or reassign the issue (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. That decision shall be documented in the comments to the issue in the Bugtracker.
The assigned issue should have state ASSIGNED.
The Developer responsible for the issue assigned to him provides a solution as a change on the version of OCCT indicated in the issue attributes, or the last development version.
The modified sources should be submitted for review and testing to the dedicated branch of the official OCCT Git repository:
In some cases (if Git is not accessible for the contributor), external contributions can be submitted as patch (diff) files or sources attached to the Mantis issue, with indication of OCCT version on which the fix is made. Such contributions should be put to Git for processing by someone else, and hence they have less priority in processing than the ones submitted directly through Git.
The issue for which 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).
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.
The issues that are in REVIEWED state are subject of certification (non-regression) testing. The issue is assigned to OCC Tester when he starts processing it. The results of tests are checked by the Tester:
Before integration into the master branch of the repository the Integrator checks the following conditions:
If the result of check is successful the Integrator integrates solution into the master branch of the repository. Each change is integrated into the master branch as a single commit without preserving the history of changes made in the branch (by rebase, squashing all intermediate commits), however, preserving the author when possible. This is done to have the master branch history plain and clean. The following picture illustrates the process:
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.
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.
Severity shows at which extent the issue affects the product. The list of used severities is given in the table below in the descending order.
Severity | Description | Weight for Bug Score |
---|---|---|
crash | Crash of the application or OS, loss of data | 5 |
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 |
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 |
minor | Incorrect behavior of a function corresponding to the description in software requirements specification. Insufficient performance of a function. | 2 |
tweak | Ergonomic inconvenience, need of light updates. | 1 |
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 |
trivial | Cosmetic bugs. | 1 |
feature | Bug fix, new feature, improvement that requires workload estimation and validation. | 1 |
integration request | Requested integration of an existing feature into the product. | 0 |
Just a question | A question to be processed, without need of any changes in the product. | 0 |
The bug statuses that can be applied to the issues are listed in the table below.
Status | Description |
---|---|
New | New just registered issue. Testing case should be created by Reporter. |
Feedback | The issue requires more information; the original posters should pay attention. |
Assigned | Assigned to a developer. |
Resolved + a resolution | The issue has been fixed, and now is waiting for revision. |
Revised + a resolution | The issue has been revised, and now is waiting for testing. |
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. |
Verified | The fix has been integrated into the master of the corresponding repository |
Closed | The fix has been integrated to the master. The corresponding test case has been executed successfully. The issue is no longer reproduced. |
Resolution is set when the bug is resolved. "Reopen" resolution is added automatically when the bug is reopened.
Resolution | Description |
---|---|
Open | The issue is being processed. |
Fixed | The issue has been successfully fixed. |
Reopened | The bug has been reopened because of insufficient fix or regression. |
Unable to reproduce | The bug is not reproduced. |
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. |
Duplicate | The bug for the same issue already exists in the tracker. |
Not a bug | It is a normal behavior in accordance with the specification of the product |
No change required | The issue didn’t require any change of the product, such as a question issue |
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) |
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. |
Won’t fix | An administrative/contractual decision has been taken to not fix the bug |
The documentation on Open CASCADE Technology currently exists in three forms:
It is strictly required to properly report the improvements and changes introduced in OCCT in all three forms of Documentation.
Every developer providing a contribution to the source code of OCC should make a relevant change in the corresponding header file, including CDL.
Making the appropriate comments is mandatory in the following cases:
The only case when the comments may be not required is introducing a modification that does not change the existing behavior in any noticeable way or brings the behavior in accordance with the existing description.
CDL description must be in good English, containing as much relevant information and as clear as possible. If the developer is unable to properly formulate his ideas in English or suspects that his description can be misunderstood, he should address to the Documentation Engineer for language assistance. Such action is completely subject to the discretion of the developer; however, the Documentation Engineer can require that the developer should provide a relevant technical documentation and reopen a bug until all documentation satisfies the requirements above.
The User’s Reference Documentation is distributed among a number of User’s Guides, each describing a certain module of OCCT. The User's Guides do not cover the entire functionality of OCCT; however, they describe most widely used and important packages.
In most aspects the User's Guides present the information that is contained in CDL descriptions for methods, classes, etc., only from a different point of view. Thus, it is required that any developer who implements a new or modifies an existing package / class / method / enumeration and adds a description of new development or changes in the corresponding CDL file should also check if this class package / class / method / enumeration or the package / class, to which the added class / method belongs is already described in the documentation and update the User’s Reference Documentation correspondingly.
3.2.3. Preparation of the Release Documentation
Before changing the bug Status to RESOLVED, the developer should provide a description of the implemented work using the "Additional information and documentation updates" field of Mantis bugtracker.
This description is used for the Release Documentation and has the following purposes:
The changes should be described from the user’s viewpoint so that the text could be comprehensible even for beginners having a very vague idea about OCCT. If the developer is unable to properly formulate his ideas in English or suspects that his description can be misunderstood, he should address to the Documentation Engineer for language assistance. Such action is completely subject to the discretion of the developer; however, the Documentation Engineer can require that the developer should provide a relevant technical documentation and reopen a bug until all documentation satisfies the requirements.
Note, that it is required to single out the changes in the OCCT behavior as compared to the previous versions and especially the changes to be considered when porting from the previous version of OCCT.
For example:
You might need to revise the code related to text display in 3d viewer to take into account new approach of using system fonts via XXX library.
The Documentation Engineer is responsible for preparation of the version Release Notes and update of the User’s Guides. If the Documentation Engineer considers that the description currently provided by the Developer is somehow inadequate or unsatisfactory he can demand the Developer to rewrite the documentation with the Documentation Engineer’s assistance.