Working with configurations in DOORS Next is extremely powerful. With configurations, not only can you relate artifacts between applications, but you also keep consistent versions. Powerful concepts can be complicated, so to simplify the usage, we recommend the following patterns (with DNG/Jira examples). This guide will help you learn how you can use changes with configurations in IBM DOORS Next Generation.
Recommendation #1: Use Global Configurations. Always.
When using DOORS Next and Configuration Management is enabled, you will always want to operate in a Global Configuration. A Global Configuration (GC) will allow you to have a consistent configuration between other OSLC Applications (such as Jira) as well as other IBM DOORS Next Components.
Once you have committed to using configurations in your DOORS Next projects, you have committed to using Global Configuration. Don’t wait to start using it; just start with some simple GC patterns.
Recommendation #2: Create (and relate) GCs for specific Releases
All change tools I know of work to named releases. It is our most basic plan and scheduling mechanism. It is valuable and straightforward to have a Global Configuration that captures the artifacts of each of these releases. The simple map of a release (for example, Jira Release) to specific Global Configuration streams is the clearest configuration.
Our links in OSLC are version-independent, pointing only to an artifact target. In the non-configuration managed world, this link goes to the latest version of this artifact. In the configuration managed world, we use the artifact link target in conjunction with a version parameter (which is the configuration).
With change management tools, we use the link target with the GC identified with the Release to get to the desired version of the artifact. The link relationships we commonly use naturally fit this pattern.
- Implements Requirement - Targets the requirement for a particular release that we need to implement.
- Affects Requirement - Targets the requirements that we identified a problem with (test result) that needs to be fixed.
- Tracks Requirement - Targets the requirements in a release that is of interest to the change point.
What is essential about these relationships is that the user quickly understands them as leveraging the release. For example, we implement a requirement for release 2.0.1; we want to link to that version of the requirement that is in the 2.0.1 stream. When we have requirements affected by an issue from release 1.0, we want to see that requirement from release 1.0 to identify if it was a requirement issue or observed poor behavior. In both of these cases, the release context is essential. What GC enables us to do is create a link to an artifact that is always pointing to the desired version.
For example on this Jira issue, all these requirement links will navigate to the version supported by AMR 1.1.0.
However, if we change the Fix Version/s (Jira targeted Release) to Release 1.0.0, then when navigated, we will now be on the Release 1.0.0 version of the requirements.
Recommendation #3: Keep Changes Personal
DOORS Next provides excellent opportunities to keep our changes in changeset or streams before we share them with others. In software engineering, we use branches to make sure changes are consistent and coherent. We now have this power with Requirements.
It is vital to use changesets to manage the changes you are performing. This allows the changes to be grouped, reviewed, and delivered as a set. If we end up with a poor change, we can also discard these as a set.
I also recommend linking your requirements change (in Jira) to the changeset to provide the change traceability. This includes status, traceability, motivation, and the ability to comment on the changes that need to be performed. All of this provides supports for us to deliver higher quality engineering artifacts.
DOORS Next actively manages this context for us and provides a quick view of the configuration. This way, we can see our configurations, changes, and management tasks in one place.
From Jira, a user can review and monitor all changes that are taking place on behalf of the change request. So when you come back from holiday, you know exactly where to start. Or, if you have a co-worker that needs a preview of the changes you are working on, they can simply go to your change ticket to see the active changes.
What is even more desirable is that from this link in Jira, a user can see what changes have been performed and the status.
When they are ready, these changes can be shared and contributed back to a shared Global Configuration. This is done via a delivery within DOORS Next and can even have a mandated approval on the Jira task to ensure the changing quality.
Recommendation #4: Report (and view) from the shared Global Configurations.
When looking to report on the content, or observing links for understanding, always used the release mapped GCs. These GCs represent the plans (or the past release plans) will be the best record of the release.
Answering such questions as to what requirements had defects reported in a specific release, or what requirements are getting implemented in an upcoming release are possible using this pattern. For example, in the AMR 1.1.0 Global Configuration, the Jira links can be reviewed and navigated to see the status of the implementation for the AMR 1.1.0 release.
It is essential to recognize a query discovers these change links to requirement artifacts. DNG will request to see links to that artifact within the current configuration. The results are the Jira tickets assigned to that configuration mapped by release. This also means if a user changes the assigned release in Jira, the update will be visible in the next access of DOORS Next (removed from the previously assigned release and visible in the newly selected release).
Results and Observations
When we apply these simple rules, we can achieve some immediate value from configurations while keeping our usage of our change tools consistent. I am confident that these patterns can be used (or adapted) by almost all teams. I also acknowledge some frequent observations that must be answered.
Observation #1: My Personal Stream has No Links!
When a user starts a new changeset and moves to a personal stream, all the external links are no longer visible! It can be surprising that the Jira ticket implements this requirement is no longer visible. Don’t worry. When working on a personal stream, it is expected you are making changes, and others shouldn’t be working on your dynamic content.
This view without implementation links should be the expectation. And who would want others performing implementations or planning on actively changing artifacts?
The resolution is rather simple. If someone wants to observe the implementation tasks, simply go to the core configuration (in this case, AMR 1.1.0), and all the tasks are visible. And when desired, switch back to the personal stream to make changes.
Observation #2: Core streams don’t allow changes in formal stream management! How can I link it?
When we become formal in our practices, we can limit the changes that take place on a stream. DOORS Next is powerful enough to require a changeset, require a related Jira ticket, or even an approved Jira ticket. From a process perspective, this is a good thing. It will be visible when these constraints have been applied because the following banner will be present.
What is challenging is DOORS Next prevents creating any links from artifacts in this mode. The DOORS Next User Interface now disallows routine planning tasks such as creating implementation tasks from your static requirements. So how do users create implementation links with these constraints?
What we learned earlier is that links to changes are actually stored in Jira and only discovered by DOORS Next. What this means is no DOORS Next change occurs, and no changeset is needed. However, we can’t initiate these new items and links directly from DOORS Next, but we have a couple of handly options.
Option 1: Create from Jira using DOORS Next Dialog
To create links, simply instigate them from the Jira side of the relationship. You can do this via the traditional dialog, such as the OSLC Dialog.
This will require you to navigate the DOORS Next browser every time, which is why we have an alternative.
Option 2: Drag DOORS Next Requirements to Jira
If you already have navigated DOORS Next, the Jira interface offers a simple drag and drop feature. Simply drag the DOORS Next ids from your browser to Jira, and links will be created!
This can ease the navigation burden when creating lots of links, you have large modules, or you are creating lots of Jira tickets.
Even with the creation coming on the Jira side, the link will appear on the DOORS Next side without needing a changeset (since the link is owned by Jira and just queried by DOORS Next). Notice the next time you hover on a DOORS Next item that you linked to; you will see that Implementation Link even without having to create changesets. Technically no change has happened on the DOORS Next data; there are just new references to it.
In this way, it is straightforward to have rigorous processes while still having the ease of managing your implementation plans.
Observation #3: My Jira links can be broken by changing the Release (or the Stream contents changing)
Some users are uncomfortable that the changing of a release in Jira may cause changes in their link data. This is a good thing. When we move a feature story to a later release, we should use the requirements for that release. Or if a Jira ticket gets moved to a new release and that requirement is not present for that requirement version, this should be made visible.
For example, in this, a Jira ticket is scheduled for release 1.1.0 and has related requirements that must be implemented. When we hover over that requirement, we get that version of the requirement in the 1.1.0 configuration stream. All is as we expect.
Now, if we attempt to pull up the implementation of this story into an earlier release, we want to see that version of the requirement. However, in this case, this requirement has yet to be created in this configuration, and we have a broken link. This is a good thing since it reminds us that we may need to pull the requirements from 1.1.0 into the 1.0 release to implement this task, or maybe we should not pull this story ahead yet.
The indicators on our links are helpful to point users to things they must resolve, and are useful to the design process. Whether they are providing us with the details that correspond to the identified release or showing us where we have information gaps, the results are better traceability and higher quality engineering.
While adopting configurations in DOORS Next may appear challenging, the results are positive and make the engineering tasks more productive. If you have questions on these patterns or need help applying Global Configurations in your process flows, please reach out to our team. We are always happy to share and learn.
I hope these simple rules can aid you to get the most out of your Jira and DOORS Next usage with OSLC Connect for Jira for Configuration Enabled projects.