Jump to: navigation, search

Difference between revisions of "Modeling Project Workflow Conventions"

m (Bugzilla)
m (Include Contributor ID)
 
(9 intermediate revisions by 2 users not shown)
Line 2: Line 2:
  
 
==Bugzilla==
 
==Bugzilla==
General guidelines for using Bugzilla on Eclipse projects is found [http://www.eclipse.org/projects/dev_process/bugzilla-use.php here], with a potential change coming to the states we use described in this [https://bugs.eclipse.org/bugs/show_bug.cgi?id=149692 bug 149692].  Unfortunately, the section on Managing Requirements is incomplete, so Modeling project recommended practices are below:
+
General guidelines for using Bugzilla on Eclipse projects is found [http://www.eclipse.org/projects/dev_process/bugzilla-use.php here], with a potential change coming to the states we use described in this [https://bugs.eclipse.org/bugs/show_bug.cgi?id=149692 bug 149692].  Some refinements to this document for Modeling are below:
 +
* The 'Version' field should indicate the product version a bug is found in, or enhancement request filed against.  This is distinguished from the 'Target Milestone' field, which is used to indicate when a fix is planned to be completed.
  
* The '''plan''' [https://bugs.eclipse.org/bugs/describekeywords.cgi keyword] should be used to indicate items expected to be completed in the upcoming release, as refined by the following fields.  Alternatively, projects may wish to continue prefixing the Summary field with '''[Plan Item]'''.  Note that the use of the keywords improves search accuracy and eliminates "pollution" of the Summary line.  The reporting query should look for either a keyword or prefix.
+
Unfortunately, the section on Managing Requirements in the aforementioned document is incomplete, so Modeling project recommended practices are below:
 +
* The '''plan''' [https://bugs.eclipse.org/bugs/describekeywords.cgi keyword] should be used to indicate items expected to be completed in the upcoming release, as refined by the following fields.  Alternatively, projects may wish to also continue prefixing the Summary field with '''[Plan Item]'''.  Note that the use of the keywords improves search accuracy and eliminates "pollution" of the Summary line.  The reporting query will rely on the 'plan' keyword.
 
* The 'Assigned To' field will indicate the individual '''committed''' to delivering plan items, while the absence of an individual name (e.g. set to the default component inbox) indicates '''proposed''' items.
 
* The 'Assigned To' field will indicate the individual '''committed''' to delivering plan items, while the absence of an individual name (e.g. set to the default component inbox) indicates '''proposed''' items.
* The 'Target Milestone' field should indicate the milestone an item is expected to be resolved in (e.g. '2.0 M1'), or simply to the major version number if the target milestone is not yet known (e.g. '2.0'). During milestone release planning iterations, items should be reviewed and milestones updated to reflect work expected to be completed in the next iteration. Setting the 'Target Milestone' field to blank indicates a '''deferred''' item.
+
* The 'Target Milestone' field should indicate the milestone an item is expected to be resolved in (e.g. '2.0 M1'), or simply to the major version number if the target milestone is not yet known (e.g. '2.0'). During milestone release planning iterations, items should be reviewed and milestones updated to reflect work expected to be completed in the next iteration. Setting the 'Target Milestone' field to blank or a future release stream indicates a '''deferred''' item.
  
 
To summarize the process:
 
To summarize the process:
 
* Items that Committers would like to appear on the project plan need to be indicated using the plan keyword or [Plan Item] prefix in the summary.
 
* Items that Committers would like to appear on the project plan need to be indicated using the plan keyword or [Plan Item] prefix in the summary.
 
* Use the 'Assigned To' field to indicate '''committed''' or '''proposed''' status.
 
* Use the 'Assigned To' field to indicate '''committed''' or '''proposed''' status.
* Use the 'Target Milestone' field to indicate first the release (e.g. '2.0'), then a specific milestone (e.g. '2.0 M3'), and deferred items (set to '---').
+
* Use the 'Target Milestone' field to indicate first the release (e.g. '2.0'), then a specific milestone (e.g. '2.0 M3'), and deferred items (set to '---' or future stream).
  
 
====Prefix List====
 
====Prefix List====
 
The following prefix conventions are used to when naming bugs to make searching easier and more obvious.  When considering new prefixes, please check the list of [https://bugs.eclipse.org/bugs/describekeywords.cgi existing keywords] first.
 
The following prefix conventions are used to when naming bugs to make searching easier and more obvious.  When considering new prefixes, please check the list of [https://bugs.eclipse.org/bugs/describekeywords.cgi existing keywords] first.
  
* '''[Plan Item]'''  -- Plan Item bugs
+
* '''[Plan Item]'''  -- Plan Item bugs (optional, used in addition to 'plan' keyword)
* '''[releng]'''  -- release engineering bugs (why not add a 'releng' component to your product list?)
+
* '''[releng]'''  -- release engineering bugs (adding a 'releng' component to your product list is recommended)
* '''[Duplicate]''' -- to mark a new bug for an existing fix as being backported to a maintenance stream. This makes it easy to find bugs by name and know which one was the backport and which the original.  
+
* '''[Duplicate]''' -- to mark a new bug for an existing fix as being backported to a maintenance stream. This makes it easy to find bugs by name and know which one was the backport and which the original. (not confusing with DUPLICATE resolution?  what about using [backport] or asking for 'backport' as official keyword?  another idea is 'clone')
  
 
'''NOTE:''' When using '''[Duplicate]''' be sure to make the new bug depend on the previous bug.
 
'''NOTE:''' When using '''[Duplicate]''' be sure to make the new bug depend on the previous bug.
Line 30: Line 32:
 
   [149692] Fixed something in this file
 
   [149692] Fixed something in this file
  
where '''149692''' is the bug opened regarding the fix. By doing this we are able to generate [http://www.eclipse.org/emf/news/release-notes.php release notes] and [http://download.eclipse.org/tools/emf/scripts/news-whatsnew-cvs.php?source=emf&bug=152615&Bugzilla=152615 bug-specific delta logs] dynamically from CVS logs.
+
where '''149692''' is the bug opened regarding the fix. By doing this we are able to generate [http://www.eclipse.org/emf/news/release-notes.php release notes] and [http://download.eclipse.org/tools/emf/scripts/news-whatsnew-cvs.php?source=emf&bug=152615&Bugzilla=152615 bug-specific delta logs] dynamically from CVS logs.  Alternatively, it should be possible to enter bug with prefixed # sign, or both # and brackets (e.g. #149692 or [#149692]) in order to account for legacy techniques - however these last two are not currently supported by the generator tools.
  
 
==== Include Contributor ID ====
 
==== Include Contributor ID ====
Line 37: Line 39:
 
   [148402] mgolubev - Do not create unlimited number of font/color resources
 
   [148402] mgolubev - Do not create unlimited number of font/color resources
  
This is required per the IP log tracking policy, and will allow for the generation of much of this log file.
+
This is required per the IP log tracking policy, and will allow for the generation of much of this log file.  With that, the addition of the 'contributed' keyword to bugs that have had committed patches will facilitate reporting.
  
==Plan Documents==
+
==Newsgroups==
 +
During the addition of MDT to Modeling, there was a lengthy [https://bugs.eclipse.org/bugs/show_bug.cgi?id=165777 discussion] regarding projects, components, and newsgroups.  The policy agreed upon by the PMC regarding newsgroup creation is summarized here:
  
 +
* Modeling projects were intentionally organized into components in order to achieve a unified/coordinated delivery of similar capabilities within a single project.  Projects are discouraged from creating subcomponents.
 +
* The Modeling PMC has agreed that component-level newsgroups should be created when sufficient interest/traffic exists for the component within the project newsgroup.
 +
* The Project/Component Lead is responsible for identifying the need for a component-level newsgroup and requesting from the Foundation, keeping in mind the Foundation’s preference for fewer newsgroups overall.
 +
 +
==Plan Documents==
 
Plan docs are simplified by linking to Bugzilla dynamically instead of statically listing bugs, which is the motivation for outlining the above process guidelines. Examples:
 
Plan docs are simplified by linking to Bugzilla dynamically instead of statically listing bugs, which is the motivation for outlining the above process guidelines. Examples:
  

Latest revision as of 16:35, 5 June 2007

This document describes some recommended practices when using Bugzilla that will provide the Modeling project with improved reporting and planning automation. It is expected that all Committers on Modeling projects will read and follow these conventions in order to maximize our overall efficiency and provide accurate project plans, as is required by the Development Process.

Bugzilla

General guidelines for using Bugzilla on Eclipse projects is found here, with a potential change coming to the states we use described in this bug 149692. Some refinements to this document for Modeling are below:

  • The 'Version' field should indicate the product version a bug is found in, or enhancement request filed against. This is distinguished from the 'Target Milestone' field, which is used to indicate when a fix is planned to be completed.

Unfortunately, the section on Managing Requirements in the aforementioned document is incomplete, so Modeling project recommended practices are below:

  • The plan keyword should be used to indicate items expected to be completed in the upcoming release, as refined by the following fields. Alternatively, projects may wish to also continue prefixing the Summary field with [Plan Item]. Note that the use of the keywords improves search accuracy and eliminates "pollution" of the Summary line. The reporting query will rely on the 'plan' keyword.
  • The 'Assigned To' field will indicate the individual committed to delivering plan items, while the absence of an individual name (e.g. set to the default component inbox) indicates proposed items.
  • The 'Target Milestone' field should indicate the milestone an item is expected to be resolved in (e.g. '2.0 M1'), or simply to the major version number if the target milestone is not yet known (e.g. '2.0'). During milestone release planning iterations, items should be reviewed and milestones updated to reflect work expected to be completed in the next iteration. Setting the 'Target Milestone' field to blank or a future release stream indicates a deferred item.

To summarize the process:

  • Items that Committers would like to appear on the project plan need to be indicated using the plan keyword or [Plan Item] prefix in the summary.
  • Use the 'Assigned To' field to indicate committed or proposed status.
  • Use the 'Target Milestone' field to indicate first the release (e.g. '2.0'), then a specific milestone (e.g. '2.0 M3'), and deferred items (set to '---' or future stream).

Prefix List

The following prefix conventions are used to when naming bugs to make searching easier and more obvious. When considering new prefixes, please check the list of existing keywords first.

  • [Plan Item] -- Plan Item bugs (optional, used in addition to 'plan' keyword)
  • [releng] -- release engineering bugs (adding a 'releng' component to your product list is recommended)
  • [Duplicate] -- to mark a new bug for an existing fix as being backported to a maintenance stream. This makes it easy to find bugs by name and know which one was the backport and which the original. (not confusing with DUPLICATE resolution? what about using [backport] or asking for 'backport' as official keyword? another idea is 'clone')

NOTE: When using [Duplicate] be sure to make the new bug depend on the previous bug.

CVS

While basic information on using CVS is found here, below are some details for using CVS to promote the automation of release notes, ip logs, etc.

Include Bugzilla Number

We commit fixes with comments preceded by the bug number, as in:

  [149692] Fixed something in this file

where 149692 is the bug opened regarding the fix. By doing this we are able to generate release notes and bug-specific delta logs dynamically from CVS logs. Alternatively, it should be possible to enter bug with prefixed # sign, or both # and brackets (e.g. #149692 or [#149692]) in order to account for legacy techniques - however these last two are not currently supported by the generator tools.

Include Contributor ID

If you're submitting a patch that was contributed through Bugzilla, you must also include that contributor's ID in the CVS comment, as in:

  [148402] mgolubev - Do not create unlimited number of font/color resources

This is required per the IP log tracking policy, and will allow for the generation of much of this log file. With that, the addition of the 'contributed' keyword to bugs that have had committed patches will facilitate reporting.

Newsgroups

During the addition of MDT to Modeling, there was a lengthy discussion regarding projects, components, and newsgroups. The policy agreed upon by the PMC regarding newsgroup creation is summarized here:

  • Modeling projects were intentionally organized into components in order to achieve a unified/coordinated delivery of similar capabilities within a single project. Projects are discouraged from creating subcomponents.
  • The Modeling PMC has agreed that component-level newsgroups should be created when sufficient interest/traffic exists for the component within the project newsgroup.
  • The Project/Component Lead is responsible for identifying the need for a component-level newsgroup and requesting from the Foundation, keeping in mind the Foundation’s preference for fewer newsgroups overall.

Plan Documents

Plan docs are simplified by linking to Bugzilla dynamically instead of statically listing bugs, which is the motivation for outlining the above process guidelines. Examples:

Other Documents / External Links