Message-ID: <1966498464.3763.1495502246121.JavaMail.jbsadmin@aojmv0003.oracle.com> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_3762_1516226602.1495502246121" ------=_Part_3762_1516226602.1495502246121 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html JBS Overview

JBS Overview

JDK Bug System (JB= S) Overview

Preface

The JDK bug system (JBS) hosted at http://bugs.openjdk.java.net/= is a JIRA instance which provides bug tracking for Projects in the O= penJDK Community. A large fraction of the bugs are associated with a JDK Release Project, such as JDK 8, and are resolved by changes to the source code for= such a Project.

In November 2006, the source code for HotSpot and javac was relicensed a= nd published as open source; this was followed by the relicensing as open s= ource and publishing of the majority of the remaining source code for JDK 7= in May 2007. Since then, the OpenJDK Community has continued to work on va= rious releases, including JDK 6, JDK = 7 and its updates, and JDK 8= .

While the history of the JDK source code under OpenJDK goes back to 2006= or so, the history of the JDK in its historical bug database stretches bac= k to 1994. Tens of thousands of JDK-related bugs from Sun's legacy bug trac= king system were migrated into JBS before JBS went live. Many of these bugs= predate OpenJDK activities. By importing this collection of JDK bugs into = JBS, the JBS bug database provides continuity of history, reaching back far= beyond the start of OpenJDK.

Bugs for some closed source technologies included in Oracle's JDK, but n= ot included in OpenJDK, are also tracked in JBS. This continues and expands= a long-standing practice of publishing bug information about closed source= code on the historical bugs.sun.com, a practice that is = as old as Java itself.

This guide describes norms for using JBS; those with sufficient cause an= d authority can deviate from these norms. This guide concerns general OpenJ= DK development and is applicable to multiple releases. The detailed polices= related to bug management have evolved over time and vary somewhat by doma= in. Documentation for a particular release or technology area should be con= sulted for logistics and details of working in that release or area.

Account Eligibility

OpenJDK Roles, Groups, and Projects are explained in the OpenJD= K Bylaws. This JBS guide will use terms defined in the Bylaws; the Byla= ws should be consulted for details.

An individual with at least one OpenJDK Project role of = Author or higher has sufficient cause to get a JBS account. A JBS accou= nt grants an individual general read and write access to issues, including = the ability to file new issues, transitioning issues among the states of th= e workflow, adding comments, changing field values (including adding and re= moving labels). The holder of a JBS account can also be the assignee of an = issue.

A user's JBS username is his or her OpenJDK name. The password reset page can be used both to reset a lost passwor= d and to establish a an initial password.

At the time of launch, self-service account creation is not supported. U= sers without an account can browse JBS anonymously or use bugreport.java.com<= /a> to view a time-delayed and simplified snapshot of bug state. Users with= out an account can also use bugreport.java.com to submit an issue. When su= ch an issue is submitted, a record is created in the Java Incidents (JI) pr= oject in JBS; at the time of launch, the JI project is not publicly visible= . Issues in the JI project have an identifier like JI-9XXXXXX, where the nu= meric portion corresponds to the bug identifier sent back to the submitter.= After an initial triage process, if the incidents needs further review, it= can be transferred to be an issue in the JDK project. When such a transfer= occurs, the issue gets a new identifier in the JDK project (JDK-8YYYYYY) b= ut references to the original JI-9XXXXXX number will be redirected.

Design considerations

The design of JBS was informed by Sun's legacy bug system used for JDK b= ugs, the use of JIRA by the JavaFX team, the OpenJDK bugzilla instance, and= various other bug tracking systems. For JBS, the natural JIRA way for mode= ling a condition was chosen by default. Configuration changes were favored = over customizations. Customizations were considered only when configuration= changes could not achieve functionality deemed necessary for JBS.

Evolution and time horizon

JBS holds issues dating back nearly 20 years in the past and the informa= tion in JBS today is expected to be of interest for more than 20 years into= the future. Therefore, a long-term and disciplined perspective will be use= d when evolving the system. For example, adding new fields will be approach= ed with caution and the information stored in any new fields will need to b= e expected to be of interest in five to ten years time.

JIRA Version

At the time of external launch, JBS is running JIRA 5.2. For general que= stions about using JIRA, refer to the extensive documentation available for that JIRA release. Over = time, JBS is expected to upgrade to newer versions of JIRA.

Projects

At the highest level, bugs in JBS are grouped into top-level project= s. At external launch, there are two public projects in JBS:

An OpenJDK Project may request that a JBS project b= e created to host its bugs by sending an email to ops@openjdk.java.ne= t. In many cases, an existing JBS project should be used rather than cr= eating a new JBS project. For example, a new JDK release would use the exis= ting "JDK" project in JBS rather than creating a new project.

A new JBS project can request a component / subcomponent configuration s= uitable for that effort. A particular project should not expect to be grant= ed further customizations, such as a novel set of status values.

Common Features across = Projects

Issue Types

When filing a new bug, there are five feature types to choose from:

The above issue types can by further refined into Subtasks. A S= ubtask is a issue type used to track breaking up an issue (not just a task!= ) into smaller pieces. The Subtasks can be resolved individually and then t= he parent issue can be resolved after all its Subtasks are resolved.

State model

Two fields represent the primary state of an issue, Status and Resolutio= n. In JBS, a number of additional fields are used to hold substatus informa= tion: Understanding for substatus values of the In Progress Status and Verification for substatus information about how a b= ug resolved with a fix was transitioned to a Closed Status.

Status

The basic state model used in JBS includes five values for the Status fi= eld:

Several additional fields record more specialized status information.

Understanding

When an issue has a status of In Progress, the Understanding field can b= e optionally used to further refine what is known about the bug:

  • Cause Known: the cause of the issue has been determined.
  • Fix Understood: in addition to the cause being known, the way to fix th= e problem is understood.

Resolution

Once an issue is Resolved or Closed, the Resolution field is also set. I= f an issue is resolved by changing a source code repository, the Resolution= field is set to Fixed. Other commonly used Resolution values are = Won't Fix, Duplicate, Incomplete, Cannot Rep= roduce, and Not an Issue.

Incomplete Issues

An incomplete issue is one where there is insufficient initial informati= on for the assignee to make further progress. JBS distinguishes between two= classes of incomplete issues: ones where more information is expected, and= ones where more information is not expected.

An incomplete bug where more information is expected is modeled as:
Resolution =3D Incomplete, Status =3D Resolved
In this state, the = submitter should provide additional information.

If no further information is provided in a reasonable period of time, an= incomplete issue can transition to a closed state. An incomplete bug where= more information is expected is not modeled as:
Resolution= =3D Incomplete, Status =3D Closed

Closing as a Duplicate

Many issues are filed in JBS more than once. When the same issue is file= d repeatedly, one issue should be closed as a duplicate of another. To clos= e a bug as a duplicate:

  • Select the Close workflow action.
  • Set Resolution to Duplicate.
  • Set Linked Issues to "duplicates"
  • Add ID of reference bug (which might remain open)

Normally the issue with the most information should be kept open; this i= s often the oldest issue.

Verification

A bug that is resolved by a fix typically goes through a process to have= the fix verified for correctness and completeness. If set, the Verificatio= n field has three possible values:

  • Verified: the fix has been successfully verified. Verification might in= clude checking that the regression test for a fix passes on all platforms o= f interest.
  • Not verified: the verification process was skipped for the fix.
  • Fix failed: the fix is faulty. (For JDK Release Projects, a failed fix = is left in a state of (Status =3D Closed, Resolution =3D Fixed, Verificatio= n =3D Fix Failed) and a new bug is opened to cover the aspects of the fix t= hat are failed, partial, or incorrect. In JDK Release Projects, an issue nu= mber can only be used for at most one push to a given repository. Therefore= , if the original bug were reopened, it could not be used to push an update= d version of the fix.)

Field Summary

Priority

The highest priority bugs are P1. The lowest priority bugs are P5. Speci= fic criteria for determining priority may vary by project.

Textual fields

There are several fields in jbs which store textual information about an= issue.

The summary is a one line title for an issue.

The description describes the circumstances behind an issue.

The comment field contains a set of comments, potentially from = many parties, relating to the issue.

Who does what

The reporter is the party who filed an issue.

The assignee is the party who is responsible for making progres= s on developing a fix.

Version Management and = Tracking

Each project defines a set of version values. These versions are then us= ed in several fields to record information about the issue:

  • fixVersion: what release is an issue intended to be fixed in/what relea= se is an issue actually fixed in? (Although in JIRA, the fixVersion is mult= i-valued, in JBS fixVersion can semantically hold at most one value.)
  • affectedVersion: what version(s) of a product are affected by an issue?= This multi-valued field can hold multiple versions that are impacted by an= issue. This field is informative and the set of releases listed is not int= ended to be exhaustive.
  • Introduced in Version: what specific version was an issue introduced in= ? Setting this field may require non-trivial investigative work; however, i= t can provide crucial information for analyzing bug escapes.

Labels

Users can associate one or more labels with an issue. Such labels are of= ten used to manage informal processes and record ad hoc information. In par= ticular, for JDK release projects, there is a set of labels defined to expl= ain why a bug fix omits a regression test= .

Environmental fields

The OS (operating system), CPU (central processing unit), and Environmen= t fields store environmental information about the system affected by an is= sue.

  • OS: there are several dozen operating system values to choose from:
    • generic: believed to impact all/most operating systems
    • linux*: a Linux version or variant
    • iOS, OSX: Apple operating systems
    • solaris*: a Solaris version or variant
    • windows*: a MS Windows version or variant
    • other: believed to impact a particular OS not available as an option
  • CPU: there are a handful of particular processor values to choose from:
    • generic: believed to affect all CPU values
    • x86, sparc, arm, ppc, itanium, etc.: distinct processor families
    • other: believed to affect some particular specific CPU value not availa= ble as an option
    • unknown: no information on CPU type

For both the OS and CPU fields, when more detailed information is availa= ble and relevant, such as particular OS patch levels or CPU steppings/versi= ons, the free-form Environment field should be used to store the additional= information.

JQL Customizations

JIRA supports both simple and advanced queries. Simple queries are compo= sed through menu selection; advanced queries are written in the JQL a query language used within JIRA. = JBS includes several extensions to default JQL:

  • regexLabel: Matches labels with a regular expression.
    Example: la= bels stating with "8":
    labels in regexLabel ("8.*&=
    quot;)
    
  • regexOption: Matches option with a regular expression.
    Example: F= inds all issues where the os field starts with "solaris":
    os in regexOption ("solaris.*")
  • regexVersion: Matches version field types with a regular expression. Example: Finds all issues with a fixed version starting with "7u&q= uot;
    fixVersion in regexVersion ("7u.*")
    

Multi-release tracking

In stock JIRA, the fixVersion/s field is used for tracking whether or no= t a fix has been applied to multiple releases. In other words, the status o= f a fix across all releases is stored in a single issue. For the purposes o= f the JDK, this was judged as not providing an adequate level of detail. In= formation of interest for JDK bug tracking across releases includes

  • the release
  • assignee for the release
  • status and resolution for the release
  • release-specific comments

Storing this information allows the bug database to easily answer questi= ons such as:

  • Does an issue impact the release I'm managing? / What releases does the= issue need to be addressed in?
  • Who needs to fix this issue? / Am I on the hook for fixing this issue?<= /li>

The solution above is implemented in JBS using a custom Backport issue type along with a custom Backport link type. Backports are full iss= ues, but only a few fields are expected to be set:

  • fixVersion: indicates which specific release a backport is targeting or= fixed in
  • assignee: holds the engineer responsible for the backport
  • Status and Resolution: hold the status and resolution for the release
  • Release specific comments: such as ones added by Hg Updater

When viewing the master bug, its backports are grouped together in a tab= ular format.

As used with Backports, semantically the Fix Version/s field has a singl= e value. This constraint is not currently enforced in the database used by = JBS, but may be enforced in the future.

The bug numbers of backports should not be used in changeset co= mments when a fix is pushed. The bug number of the master issue should be u= sed in changeset comments for all releases into which a fix is pushed.

(Note that a backport from an earlier release to later one, such as JDK = 7u6 to JDK 8, is just a backport going in a negative= direction.)

Further Note: The 'hgupdate-sync' label is used to denote bug records wh= ich are already fixed in a previous release. When code lines are synced a n= ew backport record will be created with the hgupdate-sync label to capture = the sync activity. For the most part, such records can be ignored since the= y indicate that the issue was resolved in an earlier update release.

JDK Project

Much of the work in OpenJDK occurs in JDK release Projects which use the= "JDK" project in JBS. Therefore, This section will discuss some = of the particulars of the JDK project.

JDK Development Practices

Typically, a JDK release Project will have a series of source code repos= itories:

  • Developer repositories: managed by developers
  • Integration repositories: where developers push their fixes, managed by= integrators
  • Master repository: after additional vetting by an integrator, fixes fro= m the integration repositories are pushed into master, managed by release e= ngineering

At a regular cadence, say weekly, builds of the master repository are cr= eated, validated, and then distributed as promoted builds.

JBS Bug Ranges

Bugs in the JDK project with a numeric value of 8000000 or higher were c= reated after the transition to JIRA. Bugs with numeric values less than 800= 0000 were imported from the Sun legacy bug tracking system, preserving the = numeric value on import. As the legacy system had a somewhat different desi= gn, there may be artifacts from the import. Bugs in the 2000000-2999999 ran= ge are for subCRs, which were analogous to backports in the Sun le= gacy system.

Security Vulnerabilities

To prevent exploits in the wild while a fix is being developed, security= vulnerabilities use a different bug handling process than other bugs. In p= articular, security vulnerabilities do not have publicly visible issues in = JBS. A suspected security vulnerability in the JDK should be reported using= the Oracle Security procedures rather than creating = a bug in JBS.

Classification Scheme

Within a project, JBS use a two-level component / subcomponent classific= ation scheme. (Subcomponents are a JBS customization not found in standard = JIRA.) New components are expected to be added only very infrequently. To e= ase long-term use of JBS, new subcomponents will only be added judiciously.= By default, an existing subcomponent should be used for new work if possib= le. To be considered for a subcomponent, an area should be expected to have= at least fifty bugs and anticipated to be of interest for several years.

The main top-level components of the JDK product (with main correspondin= g OpenJDK lists, if any) include:

For the libs areas, the primary name of the subcomponent will be the pac= kage of the API in question. When a more detailed classification within the= technology area of a package is needed, the package name will be followed = by a colon (":") and a name for the more detailed area. For examp= le, in the core-libs component, there will be subcomponents like:

  • java.lang
  • java.lang:class_loading
  • java.math
  • java.util
  • java.util:i18n

In the tools component, subcomponents will primarily correspond to comma= nd names in $JDK/bin like, jar, javac, and javap.

Other materia= l particular to the JDK project

For JDK release Projects, an Hg Updater process on the Mercurial servers= largely automates the setting of several fields. When a fix is pushed to a= team integration repository (like TL), Hg Updater sets:

  • Status =3D Resolved
  • Resolution =3D Fixed
  • Resolved in Build =3D team
  • Adds a comment including the changeset URL

When an integrator pushes a fix to master, Hg Updater sets:

  • Status =3D Resolved
  • Resolution =3D Fixed
  • Resolved in Build =3D master
  • Adds a comment including the changeset URL

When release engineering promotes a build, Hg Updater sets Resolved in B= uild =3D $BUILD_NUMBER for the bugs fixed in that build.

A result of the Hg updater automation is that once a development enginee= r has pushed a fix to an integration repository, that engineer is not expec= ted to update the Status value further for the lifetime of the bug.

If a bug tracked in the JDK project is addressed by making a change in a= non-JDK repository (such as a doc repository or web staging SCM/CMS), the = "Inapplicable" Resolved-in-build value is used.

There are a number of special version values:

  • tbd_major and tbd_minor: used to target a fix to some unspecified major= or minor release, respectively.
  • 7-pool, 8-pool, etc.: some unspecified future update release in a parti= cular update train.

When a bug is actually fixed, the fixVersion field must be changed to a = specific release value rather than some general value. The Hg updater proce= ss will perform this task.

The special version values like tbd_minor should not be used in= the affectedVersion field; only version values corresponding to actual rel= eases should be used.

When a JBS issue is discussed on an OpenJDK mailing list, such as a revi= ew request, it is recommended to include a link to the OpenJDK thread in a = comment in the JBS issue.

Questions and Comments

General questions about JBS can be sent to discuss@openjdk.jav= a.net.

Feature requests for JBS itself can be sent to ops@openjdk.java.ne= t.

Conclusion

Hofstadter's Law: It always takes longer than you expect, even when yo= u take into account Hofstadter's Law.
=E2=80=94 Douglas Hofstadter, G= ödel, Escher, Bach: An Eternal Golden Braid

http://mail.openjdk.java.net/mailman/listinfo/core-libs-dev

------=_Part_3762_1516226602.1495502246121--