Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "EclipseLink/Development/Process"

(Code Submission)
 
(17 intermediate revisions by 5 users not shown)
Line 1: Line 1:
===EclipseLink Development Process===
+
This page describes the process committers should use for developing and submitting code to EclipseLink. All code that is checked into the EclipseLink source repository should have gone through the following steps:
  
This page describes the process committers should use for developing and submitting code to EclipseLink.
+
__TOC__
  
====Code Submission====
+
=== Legal requirements ===
 +
* All committers or patch contributors must sign CLA
 +
** visit https://projects.eclipse.org/user/login/sso and "sign" the CLA
  
All code that is checked into the EclipseLink SVN should have gone through the following steps
+
=== There is a documented reason for the change ===
 +
* For bugs, this means an entry in bugzilla
 +
* For features this means there is an enhancement in bugzilla, a [[EclipseLink/Development/DesignDocs/DesignTemplate|Design Specification]] that describes the goal for the feature, how it is used, and an up to date design description of the feature
  
* There is a documented reason for the change
+
=== Code has been tested ===
** For bugs, this means an entry in bugzilla
+
* New regression tests must be added to completely test the feature or bug
** For features this means there is an enhancement in bugzilla, a [[EclipseLink/Development/Process/Template | Feature Specification]] that describes the goal for the feature and how it is used, and an up to date view of how the feature is designed. 
+
* An accepted set of regression tests for the whole project must pass
* Code has been reviewed
+
** Code changes should be attached to the bug in the form of an SVN patch and a notification should be sent to the eclipselink-dev mailing list
+
** The root of the SVN patch should be the root of the branch on which the patch is intended to work.  (i.e. for a patch to the trunk, the root should be org.eclipse.persistence/trunk)
+
** If the code goes through multiple iterations, not only should the new patch be attached to the bug, but the old patch should be obsoleted in bugzilla
+
** It is the committer's responsibility to ensure that at least one other committer has reviewed the code and agrees it should be committed
+
** If there are committers that disagree that the code should be committed, the committers with opposing views should work to come to an agreement and if they do not, ask the EclipseLink Architecture council for guidance
+
* Code must be tested
+
** New regression tests must be added to completely test the feature or bug
+
** An accepted set of regression tests for the whole project must pass
+
* When the code review has been completed the code can be committed into SVN.  A descriptive comment that references the bugzilla link or the feature name should be included with the check-in
+
* When the code is checked in:
+
** For bugs, the bugzilla entry must have the final SVN patch attached to it and a short description of the fix should be added to bugzilla
+
** For features, you must ensure both the functional specification and the design specification reflect the state of the current code
+
** For both, send and email to eclipselink-dev and (when applicable)update bugzilla with the following information
+
*** The name of the feature or the number of the bug
+
*** A short description of the bug
+
*** A pointer to the new tests for the bug, and if they require any special configuration, a description of how to run them
+
*** A list of the tests that have been run
+
*** The name of the committer who reviewed the bug
+
*** A link to any related specifications (Functional Specifications, Design Specifications)
+
  
If you want to do a check-in that does not follow this process, send an email to the eclipselink-dev mailing list explicitly saying you are hoping to not follow the process and describing your reasoning.  This should only be done in exceptional cases
+
=== Patch prepared ===
 +
* To get more information on working with Git source code repository please read: [[EclipseLink/Development/Process/Git | EclipseLink Git]]
 +
* Code changes should be attached to the bug in the form of a patch
 +
* There should be 1:1 mapping between patch and BugZilla issue (if that is not possible or inconvenient for specific reason, Bugzilla issue can be used as an umbrella for other issues)
 +
* The patch should be generated against branch on which the patch is intended to work
 +
* If the code goes through multiple iterations, not only should the new patch be attached to the bug, but the old patch should be obsoleted in bugzilla
 +
* All commits must be signed-off:
 +
** <code>git commit --signoff</code>, or if already committed: <code>git commit --amend --signoff</code>
 +
* Usual command to generate the patch from last commit:
 +
** <code>git format-patch -1</code>, or <code>git format-patch -M1 -1</code> if there are moved/renamed files
  
== Templates ==
+
=== Code has been reviewed ===
 +
* [[CodeReviewChecklist]] should serve as a guideline for both committer to verify his submission against it, as well as a checklist for reviewer to verify all important aspects of the change have been covered
 +
* Notification as request for review should be sent to the eclipselink-dev mailing list containing:
 +
** The name of the feature or the number of the bug + its short description
 +
** A pointer to the new tests for the bug, and if they require any special configuration, a description of how to run them
 +
** A link to any related specifications
 +
* It is the committer's responsibility to ensure that at least one other committer has reviewed the code and agrees it should be committed - this is marked in BugZilla by adding '+' Review for the submitted patch by reviewer
 +
* It is reviewer's responsibility to respond within a reasonable timeframe
 +
* It is not allowed to commit change without completed review. If there are committers that disagree that the code should be committed, the committers with opposing views should work to come to an agreement and if they do not, ask the EclipseLink Architecture council for guidance
 +
* Note that for following types of checkins review is not required:
 +
** reverts of previous commits (which are e.g. breaking tests or some other functionality)
 +
** trivial RE/build changes
 +
** code formatting changes
 +
* When providing updates based on review, keep changes for every revision in a separate commit to allow reviewers to easily verify only the incorporated changes
  
* [[EclipseLink/Development/Process/Template | Feature Template]]
+
=== Check-in process ===
 +
* When the code review has been completed, the code can be committed into repository. The commit message must include:
 +
** a descriptive comment that references the bugzilla issue #
 +
** summary of the issue/feature
 +
** name of the committer who reviewed the bug
 +
** list of tests that have been run to verify the change
 +
* For bugs, the bugzilla entry must have the final signed patch attached to it and a short description of the fix should be added to bugzilla
 +
* For features, you must ensure the design specification reflects the state of the current code
  
==Development Process TODO List ==
+
=== Exceptions ===
 
+
If you want to do a check-in that does not follow this process, send an email to the eclipselink-dev mailing list explicitly saying you are hoping to not follow the process and describing your reasoning. This should only be done in exceptional cases.
* Build template for Functional Specification
+
* Build template for Design Specification
+
* Define the set of tests that is in our SRG - i.e. The tests that must pass for all submissions
+
* Create a document describing how to add and run tests
+

Latest revision as of 01:34, 18 April 2015

This page describes the process committers should use for developing and submitting code to EclipseLink. All code that is checked into the EclipseLink source repository should have gone through the following steps:

Legal requirements

There is a documented reason for the change

  • For bugs, this means an entry in bugzilla
  • For features this means there is an enhancement in bugzilla, a Design Specification that describes the goal for the feature, how it is used, and an up to date design description of the feature

Code has been tested

  • New regression tests must be added to completely test the feature or bug
  • An accepted set of regression tests for the whole project must pass

Patch prepared

  • To get more information on working with Git source code repository please read: EclipseLink Git
  • Code changes should be attached to the bug in the form of a patch
  • There should be 1:1 mapping between patch and BugZilla issue (if that is not possible or inconvenient for specific reason, Bugzilla issue can be used as an umbrella for other issues)
  • The patch should be generated against branch on which the patch is intended to work
  • If the code goes through multiple iterations, not only should the new patch be attached to the bug, but the old patch should be obsoleted in bugzilla
  • All commits must be signed-off:
    • git commit --signoff, or if already committed: git commit --amend --signoff
  • Usual command to generate the patch from last commit:
    • git format-patch -1, or git format-patch -M1 -1 if there are moved/renamed files

Code has been reviewed

  • CodeReviewChecklist should serve as a guideline for both committer to verify his submission against it, as well as a checklist for reviewer to verify all important aspects of the change have been covered
  • Notification as request for review should be sent to the eclipselink-dev mailing list containing:
    • The name of the feature or the number of the bug + its short description
    • A pointer to the new tests for the bug, and if they require any special configuration, a description of how to run them
    • A link to any related specifications
  • It is the committer's responsibility to ensure that at least one other committer has reviewed the code and agrees it should be committed - this is marked in BugZilla by adding '+' Review for the submitted patch by reviewer
  • It is reviewer's responsibility to respond within a reasonable timeframe
  • It is not allowed to commit change without completed review. If there are committers that disagree that the code should be committed, the committers with opposing views should work to come to an agreement and if they do not, ask the EclipseLink Architecture council for guidance
  • Note that for following types of checkins review is not required:
    • reverts of previous commits (which are e.g. breaking tests or some other functionality)
    • trivial RE/build changes
    • code formatting changes
  • When providing updates based on review, keep changes for every revision in a separate commit to allow reviewers to easily verify only the incorporated changes

Check-in process

  • When the code review has been completed, the code can be committed into repository. The commit message must include:
    • a descriptive comment that references the bugzilla issue #
    • summary of the issue/feature
    • name of the committer who reviewed the bug
    • list of tests that have been run to verify the change
  • For bugs, the bugzilla entry must have the final signed patch attached to it and a short description of the fix should be added to bugzilla
  • For features, you must ensure the design specification reflects the state of the current code

Exceptions

If you want to do a check-in that does not follow this process, send an email to the eclipselink-dev mailing list explicitly saying you are hoping to not follow the process and describing your reasoning. This should only be done in exceptional cases.

Back to the top