Mike MacDonagh's Blog

Somewhere in the overlap between software development, process improvement and psychology

Tag Archives: release

Epics or Integration Scenarios?

Many teams I’ve worked with struggle to make sense of their huge backlogs of stories, struggle to explain the scope of a release and current work – and most importantly, struggle to explain how the stories they’re working on contribute to business value!

All of these problems are killers when it comes to joining up what a development team is doing to a corporate portfolio, governance and milestones. Features and business benefits seem to be too high level, stories seem to be to low level.


 Epics

A common approach to trying to solve these problems is to use “epics”. Originally intended to just be another type of story (one that was too big for a sprint) “epics” are now commonly used in a requirements hierarchy by teams and organizations. I’ve seen loads of backlogs where every story had an epic “parent” – sometimes even a 1-1 mapping from epics to stories(!!!!). I know that some process frameworks recommend this approach, but I don’t and here’s why:

Stories can just be on a backlog

Stories don’t have to have a parent. A backlog made up of stories is just great, it doesn’t need a hierarchy that’s a Work Breakdown Structure using some agile-y sounding words to hide the fact. A backlog isn’t a gantt chart, stop trying to turn it into one by stealth!

Actual epics are useful for teams

“Epics” in their original form were simply stories too big for a sprint, sometimes that just creeps up on you so it’s useful to be able to tear up a big story and replace it with some smaller ones. By formalizing a Feature -> Epic -> Story hierarchy as an “agile at scale” process I’ve seen corporate processes become protectionist over epics, trying to use them to fix scope, counting and metricating them to the extent that teams can’t simply discover some of their stories are epics.

Bigger stories need more than a sentence

I know that a story can have more elaboration than the standard form of “as a user I want to…” but few stories in the wild have more than a sentence (you’re often lucky if you find some with acceptance criteria). I find that describing how various stories contribute together (especially when across several teams and/or systems) to deliver business value I need more than a sentence. I often need a diagram or a paragraph or two.

“Epics” sound silly

What’s in a name? Would a rose by any other name smell so sweet? Probably. Names shouldn’t be that important and yet they are, what we call things has a significant impact on how people represent them. “Epics” are part of the money spinning agile movement’s language. They either sound silly to businesses or as a way to pretend they’re doing “agile at scale” by adopting the term for their portfolio requests.

I like Integration Scenarios more

Ok, so this is clearly subjective and personal but that’s kinda my point. I don’t use process elements because someone told me to, and I don’t think that something like Integration Scenarios are always better than epics. I prefer to pick and choose different tools for different jobs. In my experience Integration scenarios are frequently a better tool for scoping, elaborating and agreeing  end-to-end threads across a system or system-of-systems so they’re one of my “go to” tools.


So what are Integration Scenarios?

Originally from Holistic Software EngineeringIntegration Scenarios

Integration Scenarios describe an end to end workflow across a Product or Product Family. Integration scenarios are threads across a number of low level requirements such as user stories that collectively deliver Business Value. They are ideally suited to describing the scope of Releases and providing the input for integration testing necessary to achieve higher levels of acceptance.

Integration Scenarios can also be used to manage cross-cutting Non-Functional Requirements and drive the discovery of Architectural Mechanisms.

Integration Scenarios provide the context for discussions around User Stories

Integration SceExample of graphical Integration Streamnarios can be described in a number of ways, ranging from textual to graphical depending on the nature of the system and the best way to achieve clarity. In all of these examples we recommend using a meaningful title, not “Integration Scenario”!

One of our favorite ways is to draw an activity diagram of user interactions using GUI mockups in the nodes with references to features/use cases/stories as appropriate. We do not recommend strictly following a diagram format but using the visual or textual elements that will communicate the scenario as effectively as possible. Story-boarding can also be an effective way of describing Integration Scenarios.

When using a graphical view we recommend including links to stories or systems that are covered by the scenario and adding rich graphics to standard modeling notation to increase communication.

Example of textual Integration Scenario Integration Scenarios using textual formats are best described as a narrative with links to contributing stories or systems.

They should ideally be no more than a couple of paragraphs that describe interactions between actors across a number of stories. Sometimes adding extra alternative or exceptional flows can be useful, in the style popularized by use cases, but if there’s a lot of “flow logic” involved then we recommend using a diagrammatic form (e.g. workflow) to avoid convoluted textual documents. Similarly adding a non-functional section indicating non-functional requirements or constraints that apply across the stories making up the scenario can be useful.

Integration Scenarios describe the dynamics between stories and how they collectively contribute to delivering business value. To that end we recommend highlighting and directly linking to the stories that make up the integration scenario. In this way Integration Scenarios add context to the mass of user stories and provide a sound basis for scoping a system, describing a release, functional architectural mechanisms, integration testing, and product acceptance.

Regardless of format we recommend that Integration Scenarios are described from the user perspective and focus on achieving business value. The choice of formats should be driven by the type of Product being developed (e.g. graphical/user facing vs. back end service) and further influenced by team experience and available tooling. We strongly advise not being concerned with the constraints imposed by formal modeling languages, the communication is important not the notation.

Example of simple graphical list view of an Integration ScenarioSometimes we wish to use Integration Scenarios as part of diagrams, even workflow/activity diagrams (e.g. for Value Stream Analysis) in which case the full text version might be a bit big. In these situations we recommend using a “zoomed out” view which just lists a title and the related stories. In fact this “elided” form of an Integration Scenario is sometimes useful for simply gathering up a collection of stories into a larger chunk for planning purposes. Story lists in these diagrams don’t have to be exhaustive, just indicative.

Practicality

Textual Integration Scenarios can be crafted in and decent rich text editor that allows for hyperlinks. We recommend trying to keep them short since the detail of the requirements should be in lower level stories or UX designs/storyboards. Instead the Integration Scenario focuses on the dynamics between requirements. A good rule of thumb is that they should be only a couple of paragraphs, and at their biggest if alternates/exceptions and nonfunctionals are included they should only be 2 or 3 pages. Creating a large number of fully documented Integration Scenarios prior to any development effort is a very bad idea as it will introduce the problems inherent in waterfall development, however elaborating the Integration Scenarios for a Release prior to development iterations/sprints or continuous flow development (with customer representation and team representation) is an excellent way to align collective understanding of scope and requirements.

Each Release should have no more than a couple of Integration Scenarios in it, if there’s more and they are not too interdependent then they can be delivered in separate Releases enabling earlier feedback cycles, (even if they are internal Releases rather than operationally deployed customer release.

Links to other elements

The H-ModelIntegration Scenarios provide a mid-level requirement type, higher than User Stories but lower than Portfolio Requests containing a lot more information than a Feature. As a result Integration Scenarios provide a unit of incremental business value which can be used for Release Planning, tying in milestones for programme/portfolio tracking and governance.

Because Integration Scenarios are constructed in a narrative form that describes a scenario, tried and tested scenario based testing methods can be applied for Integration testing.

Integration Scenarios also provide a useful starting point for understanding Solution Architecture, in the case of Product Families or systems of systems,  and even System Architecture in terms of indicating structure and identification of mechanisms. It is possible to resonate architectural structure with Integration Scenario structure although there is a risk of inappropriately introducing a Homomorphic force to the architecture.

By aligning Integration Scenarios with Integration Streams, Releases and Milestones we can focus the various views of Portfolio Management, Programme Management, Project Management, Architecture, Delivery, Quality, Deployment, Acceptance and and Business Change onto Releases at the center of the H-Model de-conflicting business management and technical delivery. Providing a context for requirements, planning and delivery Integration Stories are a common currency for the entire IT organization to work with.

Integration Modeling

Example of an Integration ModelIntegration Scenarios can also be used as part of Integration Modeling (creating scope diagrams) to indicate which actors/systems sets of requirements interact with, helping to clarify overall scope and identify potential gaps in scope.

If using Integration Modeling we recommend color coding Integration Scenarios based on priority (e.g. Musts, Shoulds etc.).

A Scoping Diagram is used to draw a picture of the primary requirements and users/interacting systems.

Read more: Scoping Diagram


What are your experiences of “Epics”, “Integration Scenarios”, “Scoping Use Cases” or other alternatives?

Advertisements

Advanced RTC SCM Streaming – Part 3 Component reuse

Basic usage of RTC Jazz SCM is easy enough but there’s what about more advanced usage? Using streams to isolate development from integration? Cross-project component reuse? Parallel branched development? Integration Streams aligned to Definitions of Done? This is the guide for that stuff.

This blog is in three parts:

  1. Development, Integration and Release Streams
  2. Streams for parallel branched development
  3. Streams for component reuse

Part 1 also covers the introduction and overall conclusions

Working with components across multiple RTC projects can present a bit of a challenge. It’s simple enough to create a stream with any baseline of any component in your repository but dealing with changes to those common components is not simple or obvious, especially if you need different visibility controls and access rights for different teams on different components.

Read more of this post

Advanced RTC SCM Streaming – Part 2 Parallel branched development

Basic usage of RTC Jazz SCM is easy enough but there’s what about more advanced usage? Using streams to isolate development from integration? Cross-project component reuse? Parallel branched development? Integration Streams aligned to Definitions of Done? This is the guide for that stuff.

This blog is in three parts:

  1. Development, Integration and Release Streams
  2. Streams for parallel branched development
  3. Streams for component reuse

Part 1 also covers the introduction and overall conclusions

Change set based SCM systems like git (SimpleGit)and RTC do away with the need for a lot of branching. You don’t need to branch to get developer isolation, to gather file changes together to understand them as an atomic set of changes related to a bit of work or to manage concurrent development of the same files on a small scale. You get all of that for free by using change sets. Developers are always in their own private personal branch separated from the rest of the team but unified by a common stream or repository. However sometimes it’s still appropriate to branch, this blog covers some of the situations when it’s appropriate and how to do it effectively in RTC Jazz SCM.

Read more of this post

Advanced RTC SCM Streaming – Part 1 Development, Integration and Release Streams

Use Case vs. User Story

Use Cases are too big to fit into a sprint/iteration! User Stories are so fine grained there’s too many too keep track of! Where’s the big picture? How to we define releases? Argh!!! I don’t know which to use!

Personally I tend to use both. I don’t think there’s any conflict between Use Cases and User Stories, in fact they’re rather complementary. Here’s how and why….

A few years ago I delivered a presentation at an agile software development conference entitled “Do requirements still matter?”. The short answer was “yes”. Most descriptions of agile iteration start with having a backlog, prioritising etc. etc. But where does the backlog come from? My answer: the Backlog Fairy; obviously.

The Backlog Fairy

Of course requirements still matter, they’re how we get a common understanding between customers and development teams of what we need to do. They’re the units by which we can incrementally build systems. In the rush to adopt agile processes a lot of teams have forgotten that they still need to start up with some lightweight analysis of scope and risk.

One of the things Use Cases are great at is capturing the big picture, showing a simple diagram of stick people and blobs that people who’ve never heard of UML can happily discuss in terms of what big bits of functionality are in and out of the system and who’s going to do them. The humble Use Case diagram. Not so easy to do that with a massive list of small stories.

However Use Cases can often be a bit too big to fit into a single development cycle but since they’re made up of a lot of different scenarios they’re easy to slice up into smaller bits. This is where I often use stories.

The advantage of Use Cases defining the scope is they’re nice chunky things to estimate and prioritise in a first pass. Of course as we get going we’ll estimate and prioritise stories for sprints/iterations but Use Cases help us prioritise requirements into Releases.

So I use a Use Case diagram to describe the high level scope of the thing to be developed. This normally takes about 5minutes to sketch. Then I use the Use Cases identified by the diagram (not documents, just the ovals on the diagram) to focus discussion on deriving stories (or use case slices) for development and testing within a sprint/iteration.

Sometimes stories turn up that don’t really fit into the early Use Case model, this is a rather good thing as it lets us challenge the understanding of scope. Does the story not fit in because it’s not really in line with the customers priorities and needs, it’s a cross-cutting or architectural concern or because we’ve missed some important part of the scope? All are important things to understand.

Working with Maven multi-module projects in RTC Jazz SCM with m2

I’ve been working with Maven projects with m2 for a while in RTC Jazz SCM so thought I’d post some notes. For reference this post covers using RTC v3.x things may change in the future. If you’re not using m2 then I’d suggest you read this blog by Philippe Krief.

First of all it’s important to understand that RTC v3 has limited support for Maven. You can setup a build definition which can call a maven goal (such as a local install) easily enough but that’s about it. The RTC build mechanism is basically a cron job with a nice web (like Hudson/Jenkins without the plugins) and Eclipse front end, it doesn’t have a deep understanding of Maven.

The whole point of Maven over Ant is that it does a lot by convention rather than specification, however in most advanced Maven project I’ve seen pom files are as big as equivalent Ant + Ivy files. Regardless I still think Maven with the excellent Sonatype Nexus is awesome (although I also like the structured bash/batch like nature of Ant as well).

Most serious Maven projects are multi-module. This is because component based development is a good thing (shameless employer plug, but it’s true, it is a good thing). Most (tending to all) multi-module projects have the following structure where “O” is a folder and “-” is a file, considering a hypothetical ProductX:

– pom.xml (the parent pom for the master/uber/product build, lists child modules)

– various files at the root of ProductX

O ModuleA

– pom.xml (for ModuleA)

– various ModuleA root files

O various ModuleA folders of stuff (such as src)

O Module B

– pom.xml (for ModuleB)

– various ModuleB root files

O various ModuleB folders of stuff

If you want to work with this stuff in RTC Jazz SCM then you need to balance the constraints of Maven m2, RTC and Eclipse. If you’re considering doing this then you’ll probably be considering moving existing Maven projects to RTC, in which case you may find a previous blog on a manual migration script useful. The only edit to this I make for Maven is to separately import the parent from the children if flattening the structure (although in most cases I wouldn’t recommend flattening).

The constraints playing against each other are:

  • Maven and plugins expect sub-modules to be in child directories as in the tree above
  • RTC doesn’t allow both an Eclipse project and root files to be at the root of a component
  • The simple case of Eclipse and RTC SCM interacting during a load from the server restricts Eclipse to only seeing projects which are represented as folders at the root of the local Eclipse workspace containing .project files.
  • Eclipse doesn’t really support parent and child projects.

I’ve found there are a number of approaches, none are perfect:

1. Flatten the structure (my opinion the worst option)

You can edit the parent pom.xml to reference the sub-modules as ../ModuleA etc. although the Maven release plugin (amongst others) don’t play well with this. Also, and somewhat fundamentally, you shouldn’t have to restructure your code based on your SCM tool.

2. Only load the relevant bits (my opinion is it’s sometimes ok)

You could just load the child modules you’re currently working on and then unload (remember to delete local files or you hit a bug) and then reload the parent when you want to do a “big” parent build. Frankly this is unacceptable from a developers perspective and will fail anyway if there’s a dependency on the parent from the children. Although in theory this may be frowned upon it’s quite common and so needs supporting by the scm tool.

3. Load then import, with auto-refresh (my preferred option)

This one is going to be more than one paragraph….

Prediction fulfilled ;p Anyway… Currently your developers may be used to a scm system where they load/copy/access files from the scm system on the local filesystem and then do an Eclipse -> Import Existing Maven projects to get all of the various goodies.

If you import the multi-module project as above but with a root folder (as an eclipse project) so it has the following structure:

O Product X

.project

– pom.xml modules)

– various files at the root of ProductX

O ModuleA

– pom.xml (for ModuleA)

– various ModuleA root files

O various ModuleA folders of stuff

O Module B

– pom.xml (for ModuleB)

– various ModuleB root files

O various ModuleB folders of stuff

Then when you do a load from Jazz SCM you’ll get in the Eclipse Project Explorer (or equivalent) ProductX correctly detected as a Maven project (or an Eclipse project with a Maven nature for the pedantic amongst you).

You can then do a normal Eclipse -> Import Existing Maven Projects based on your workspace/ProductX/… (taking care not to select “Copy projects into workspace”) You’ll then get in Project Explorer (or whatever):

ProductX (info about rtc scm links)

ModuleA

ModuleB

In this view ModuleA and ModuleB exist in two places: as projects referenced in the workspace but apparently outside of RTC SCM control; as a folder structure under ProductX/ModuleA and ProductX/ModuleB.

This has the following advantages:

  • Cross-project dependencies resolve
  • You can run the parent/uber pom goals and the child pom goals without reloading anything
  • You can shift focus between the child-modules and parent structure without reloading anything

If you edit files in ModuleA and ModuleB under the folder hierarchy of ProductX then Pending Changes will keep track in the normal way but if you edit a file under the apparent “root level” ModuleA and ModuleB then Pending Changes won’t unless you do a “deep refresh”.

Alternatively just go to Eclipse -> Window -> Preferences ->  General -> Workspaces -> Refresh automatically (er… I think, I’m doing this from memory, hence the lack of screenshots). You can then add “edit files tracked by Pending Changes at either Product or child module level” to the advantages above.

So this option sounds great so far, what are the downsides?

This solution maintains the hierarchical structure between ProductX and it’s child modules and as such constrains everything from ProductX downwards to be in the same Jazz SCM component as eclipse projects can only be seen (without far too much fiddling) if they’re root folders in components. This may not seem like such a big deal but components are the lowest level of baseline (or label) in Jazz SCM. In a tightly coupled cohesive single architecture this might not be a problem but if you want to reuse any of these modules (at a code level) or have a separate ownership it will be a problem. It’s also very common to have dependencies from child modules to parent projects (which may initially seem to resolve if they’re in the local ~/.m2 repository).

Having said that source code dependencies between components lead to brittle architectures, binary dependencies are far superior, and made much easier by the use of things like Ivy/Maven and Nexus.

Other considerations

The point above above binary vs. code dependencies can be argued until the cows come home and go out again (an extended metaphor), especially if you consider project/product/team/release boundaries. I’m not going to pretend to answer those with an academic silver bullet here, the important thing I hope you take away from this blog is that there are pros and cons to all of these approaches, balancing those with the needs of your team/architecture/project/organisation are not easy. Shameless plug: Give me a call if you need help

Eclipse refactoring isn’t dealt with well by Jazz SCM, especially between Eclipse projects in and “out” of source control (advocated by option 3 above). Expect a lot of “remove/add” combinations if you are doing anything more than a trivial set of file changes. This is also a problem for the ClearCase <-> RTC automatic synchroniser developed by the excellent Samecs however I know that I, others and Samecs are pushing for improvements on this from IBM.

This post has been very scm focussed but what about build and release? The RTC build engine understands maven to a limited degree and can easily invoke maven builds for information on integating the maven release process see How to do maven releases with Jazz SCM

%d bloggers like this: