Two JIRA projects
We use JIRA for managing bugs, RFEs, and engineering tasks in OpenDJ. OpenDJ has two JIRA projects associated with it:
- OPENDJ - this JIRA project should be used for tracking issues against the OpenDJ server. If you are unsure which project to use then use this one
- OPENDJSDK - this JIRA project should be used for tracking issues against the OpenDJ SDK libraries and toolkit.
We use two JIRA projects because the server and SDK have independent release cycles, although we aim to synchronize releases of major versions of the two components. For example, we have released SDK 3.0.0 and the server 3.0.0 at the same time, but 3.1.0 of the SDK and 3.1.0 of the server will likely be released separately, and it is possible that one or neither of them are ever released.
As with most projects we categorize issues into bugs, RFEs, and engineering tasks. Some projects opt to use issue types whose names are aligned with agile development terminology, in particular epics, stories, and bugs. In OpenDJ we have taken a hybrid approach of agile development tasks and traditional tasks. In particular, we don't use "stories" for use cases and instead use "features" and "improvements", simply because we feel that they are more meaningful to people unfamiliar with agile development terminology. So what types of issue do we have and when should you use them? We have two sets of issue types: those that we expect OpenDJ community users and developers to use, and those that should only be used by OpenDJ community developers.
Issue types intended for OpenDJ community users and developers
These issue types should only be used for issues whose resolution will change the behavior of OpenDJ as observed by end-users. In particular, do not use these issue types for engineering tasks such as refactoring code and other cleanup, testing and QA, build process, and project management tasks. Generally speaking, it should be possible to complete an "improvement" or "new feature" within one sprint, although we don't strictly enforce this. We may convert these issues into epics and break them down into smaller units of work if they are obviously very large pieces of work.
- Bug - use this issue type when you want to report unexpected behavior in OpenDJ. Please ensure that you provide a description of the expected behavior, the observed behavior, and the steps to reproduce the behavior
- Improvement - use this issue type when you would like to see an existing capability enhanced in some way. For example, use this for performance, reliability, or documentation improvements, etc. You may also use this issue type for minor functional changes to existing features, although choosing between "improvement" and "new feature" can be quite subjective
- New Feature - use this issue type when you would like to see a new capability added to OpenDJ.
Issue types intended for OpenDJ community developers only
Use these issue types for code refactoring, testing and QA, build process, and project management tasks.
- Epic - use this issue type for representing road-map themes and grouping of related features and improvements. Epics appear on our Agile board. It is often easier to create and manage epics directly from the Agile board
- Task - use this issue type for any engineering work that is not a QA task nor a bug, improvement, or new feature as defined above. In particular, this issue type must be used for development work that does not change the behavior of OpenDJ from the point of view of our end-users. Tasks include: refactoring of code, unit tests, changes to our build system, project management tasks, investigations, etc
- QA Task - this issue type is reserved for our QA team and must be used for issues relating to our functional test frameworks
Sub-task - use this issue type when breaking down other issues into small items of work. In practice we very rarely use this issue type.
Creating new issues
When creating a new issue please provide the following:
- concise and helpful summary: please remember that engineers will often view issues in list format and the summary is all they can see, so a good summary really helps engineers process large lists of issues efficiently. If you are logging a new feature or improvement then try to provide a one line summary of the use case. The summary should represent the "X" in "As a user I would like to X". If you are logging a bug then try to summarize how the behavior deviates from expectations rather than simply specifying the observed error. For example, prefer "Exception observed in error log when exporting a backend" over "com.persistit.exception.InUseException: Thread Worker Thread 59 failed to acquire reader claim on Page 861,935"
- description: provide more details about the bug or enhancement. Some people forget.
- affects version: for bugs please report the version of OpenDJ that you are using. Please don't include other versions unless you have reproduced the issue against those versions
- environment: specify the OS, JVM version, etc if you think it's relevant
- component: this helps us categorize and triage issues. There's no need to specify a component if you are unsure.
Unless it has already been agreed in advance, please do not assign issues to engineers, specify a "fix version", nor specify a non-default priority.
Evaluating issues (triage)
Initially all issues are created in state OPEN and will appear in our agile backlog. At this point it is the responsibility of the OpenDJ engineering team to evaluate issues as soon as possible. Failure to do so may result in a critical issue being reported but not prioritized and, therefore, not fixed. The purpose of triage is to determine whether an issue is valid, should be resolved for the next release, or whether it should be postponed for a later release. Once an issue has been triaged it will end up in one of the following three states:
- resolved: the issue was invalid for some reason, a duplicate of another issue, or simply something that we know we'll never fix
- valid for next release: the priority is updated if needed and the issue "fix version" is updated to reflect a future release of OpenDJ. The issue remains open. This state simply communicates a desire to resolve the issue for the next release, but does not mean the issue will be fixed, although we will typically ensure that all blockers are fixed before release
- postponed: the "fix version" is left empty and the issue is transitioned to the "postponed" state, indicating that we do not expect to resolve the issue for the next release.
Once a major version of OpenDJ has been released all postponed issues are "reopened" for re-evaluation and the fix version field for any remaining unresolved issues is removed. The entire list of unresolved issues is then re-evaluated for inclusion in the next major release.