WANTED: Seeking Single Agile Knowledge Development Tool-set

I'll be presenting at Agile2009 in Chicago on the Tools for Agility stage on Tuesday 25 August, 4:45pm-5:30pm.


Here is my session description from the Agile2009 conference website (download PDF here)

WANTED: Seeking Single Agile Knowledge Development Tool-set

Aren’t code, backlog-items, tests, designs & documents all just different forms of system knowledge at different levels of detail? Why can’t the same tools help refactor, browse, search, and provide build/test automation for non-code forms of knowledge without requiring a separate tool/repository for each format? This talk is intended as a challenge to tool vendors/developers to see how this simple treatment of all non-code items as part of a single, unified project knowledge-base can be at once both immensely powerful, and imminently practical, without requiring too much added complexity.

Process/Mechanics

Approximately ~30 minutes of slides/presentation to “make the case” for why this approach is useful and desirable, followed by discussion of challenges (to and from tool developers/vendors, as well as the rest of the audience) as to its usefulness and benefits, and why their current tools can’t easily do so and why the should or should not be easy to enhancement them to do it.

Outline

Software development as knowledge development

• Source-Code as knowledge
• Requirements (Stories) and Tests as knowledge
• Other usable forms of project knowledge (e.g., build scripts & configuration, build/test result reports version control history/comments, online help & other supporting docs)

How would I do this?

• Refactoring Knowledge (thinking about the rest of the “knowledge” the way we think about the code, and its habitability, navigability, and structure/refactoring)
• Applying other agile-practices (like TDD, Continuous Integration, etc.) to non-code knowledge development
• Wiki-based skins, DSLs, and use-cases/design as domain-driven Wiki-word definitions
  • Patterns (giving things names), Retrospectives results and lessons learned
• Viewing, searching EVERYTHING (even the code) via wiki?
• The “Wu-Wei” of Traceability (Tracing without Tracing)
• Versioning and operating on wiki-like entities, just like with code (e.g., making “working copies”, branches and tags)

DISCUSSION & CHALLENGE: Why can’t (or how can) YOUR tools do this!

Begin audience discussion/dialogue: Why can’t a tool like Eclipse or a Wiki-based CMS (such as Confluence) be used as a front-end to browsing/refactoring and navigating ALL the knowledge of the system? (not just code, but stories, tests, build/config data, CI reports, backlog, retrospective lessons).
What makes it easy/hard for these and other tools like any of the following to do this, or to be simple “skins” or plug-ins on top of only a handful of tools instead of a whole kitchen sink full of separate tools and repositories.

• Eclipse, Confluence, Twiki?
• FIT, Fitnesse, Contour
• Doxygen / Javadoc
• Trac / Agile-Trac?
• Jira / Remedy

See also a blog-entry of mine entitled Can I have just one repository please?

Learning outcomes

• Thinking about Agile development as knowledge management & creation
• Current barriers to using agile techniques and supporting tools for non-code artifacts
• What do refactoring, TDD, continuous integration, etc. mean for non-code artifacts (and why you should care)
• Use of wikis for organizing, structuring and refactoring ALL system knowledge
• Why manual traceability is unnecessary (and even comes for free) when using such an approach

Primary target persona

• Tomas Tool-smith/Tool-vendor

Other target personas

• Billy, Business Analyst
• David, Agile Developer
• Patricia, Project Manager
• Tara, Tester

(download PDF here)

BOOK: Clean Code - A Handbook of Software Craftsmanship

My review of Robert Martin's (and the rest of the folks at ObjectMentor) book Clean Code: A Handbook of Software Craftsmanship was just published in the April 2009 issue of the Agile Journal.

Robert ("Uncle Bob") Martin and the folks at ObjectMentor have written a new book that should be required reading for all programmers! When it comes to writing clear and maintainable code, cleanliness is indeed next to godliness, and we should all follow the Boy Scouts' Rule whenever we write or modify any piece of code: leave the place cleaner than when you found it!

Robert C. Martin is one of the giants of object-oriented design, and a founding father of the agile manifesto and of agile software development. More recently, he helped kickstart the software craftsmanship movement, which gained much attention from his keynote at Agile2008 and subsequent talks on craftsmanship and ethics.

...

If you are at all serious about programming, then as soon as you finish reading this review you should get your hands on Clean Code as fast as you can! Get it. Read it. Learn it. Then live it!

Read the full review

Additional resources related to the book are:

• Uncle Bob's article "What is Clean Code?" which is an online version of the first chapter of the book
• PDF of an excerpt from the book, including the TOC, Foreword, Introduction, and Chapter 1
• Clean Code Tip of the Week #1 and other Clean Code tips available online from the "Extras" tab of the InformIT site for the book

Assigning Code Ownership-Policy Ownership

Jurgen Appelo has an interesting article on StickyMinds entitled "Code Ownership Re-Visited"

Jurgen prefers the term "artifact assignment" rather than "code ownership" and explains there are 4 methods of artifact assignment:

1. Local Artifact Assignment (LAA) delegates policy to subsystems and subsubsystems (etc.)
   
2. Authoritarian Artifact Assignment (AAA) assigns change/access-control access-control of of ALL related artifacts to a single individual "benevolent dictator" who approves/authorizes all changes and who may also assign individual change-tasks to developers
   
3. Collective Artifact Assignment (CAA) assigns the whole team (rather than any one person) as collectively accountable for all its artifacts
4. Individual Artifact Assignment (IAA)

He also provides a nice set of criteria to help decide which policy to use.

This seems very different from the 4 kinds of ownership I described in "Situational Code Ownership: Dynamically Balancing Individual -vs- Collective Ownership" where I define what amounts to Non-Ownership (which can sometimes be the result of Dictatorship), Individual Ownership, Stewardship, and Collective Ownership and show how each maps to a corresponding leadership-style of the Situational Leadership Model.

So what gives? What explains this difference?

• I think Jurgen would probably consider Stewardship as a weak form of Individual ownership (many others would too, though I staunchly disagree for reasons elaborated in the aforementioned article).
• Authoritarian Assignment would be akin to the form of Non-Ownership that results from Dictatorship (or "director-ship" to be more precise) where assignments are made per modification/tasks by a director (or "benevolent dictator")
  
• I would argue that the first two methods Jurgen describes above aren't really artifact-assignment policies, but instead are assignment-ownership policies: They're not so much about making a decision among ownership-policies as they are about making a policy for ownership decisions. Rather than deciding "who should own which artifacts", they decide "who should own the decision" to make such artifact assignments.

In other words, the first two policies Jurgen defines are about decision-rights to assign modification-rights to owners, and not about the modification-rights (or ownership assignments) themselves. As such, it raises an important point taken for granted in my article and in so many other discussions on this topic. Most of the prior discussion probably has assumed that the decision about which ownership-policy to adopt was made either "by the team" or by the team's "leadership" (that might be a manager, a technical-lead, a project-lead, or any combination thereof).

Another common assumption is that such ownership is defined along "architectural" boundaries such as individual artifacts/files, classes/modules, or packages, components and subsystems. Other possibilities are:

• Functional boundaries (e.g., by feature/feature-set, story/theme/epoch, or use-cases)
• Project boundaries (e.g., work-breakdown-structures, tasks, activities)
• Role/discipline specialization boundaries (e.g., requirements, tests, models, database, UI, programming-language, user/help documentation, etc.), and even ...
• Configuration/variation boundaries (e.g., version, variant, branch, platform). In fact some of these stretch across multiple dimensions of a project/product and might even be used in combination.

With Agile development, the emphasis is to break-down communication boundaries and any corresponding separation related to role, or phase, or physical boundaries and to instead prefer customer-determined boundaries of "scope" and "deliverable value" (e.g., stories, features or MMFs, use-cases, etc.).

So you will see a definite (but time-constrained) assigning of things like tasks to owners and stories (though the "owners" sign-up rather than "being assigned"). Those kinds of boundaries encourage closer and more frequent communication rather than separate & isolated (and less frequent) communication.

In the end, with Agile methods, it's all about maximizing learning and knowledge sharing & transfer rather than compartmentalizing knowledge into pigeon-holed roles and responsibilities. One opts for "separation of concerns" without "separation of those concerned" (work is isolated and separated, but not people).

Best Kept Secrets of Code Reviews

The folks over at SmartBear software have written a nice little book entitled The Best Kept Secrets of Code Reviews. It's free if you go over to their webpage and ask for it (you have to fill out a registration form, and it takes a few weeks to arrive, but they havent spammed me at all since I registered with them a few months ago).

This is a pretty good book and it is VERY pragmatic! It is applicable to Agile development too! [You don't have to do Pair-Programming to be Agile! Pairing is part of XP, which is one particular agile method -- several other agile methods do not require it.]

SmartBear also has a pretty neat suite of tools that look to me like they would be REALLY USEFUL for an organization trying to streamline some of its otherwise heavyweight processes for peer-reviews and related quality metrics:

• CodeCollaborator - Automation for paperless peer code-reviews
  
• CodeReports - Continuous source code metrics over time.
  
• CodePickle - Suspend & resume code changes in local developer sandboxes (implements the PrivateVersions pattern without using version-control branches)
  
• CodeReviewer - automated peer-to-peer code reviews across remote sites
• CodeHistorian - Data-mining and visualizations for version control systems.

And "No!" they did not ask me to blog or say anything nice about them or their products! I'm simply coming from the perspective of someone in a large organization who has witnessed a lot of homegrown and heavyweight processes and tools for these kinds of things, and don't see too many commercial tools addressing the peer-review aspect of development and trying to make it lighter-weight and better-integrated with version-control and the rest of SCM.

The have some other nice resources too:

• Agile Peer Review: Methods, and Results (Powerpoint Presentation)
• The Case for Peer Code Review
• Brand New Information about Code Reviews
• 11 Best Practices for peer code review
• 2500 Reviews at Cisco® - The Largest Case Study of Code Review, Ever
• Why formal inspections fail
• Team-Building for the Cold, Dark, and Alone
• Compare 5 styles of review
• Pros & Cons of Four Types of Review
• Social effects of peer code review

Looks like a lot of "good stuff" to me!!!

Recursive Make Reconsidered

In an earlier blog-entry reviewing the book Code Craft, I mentioned the classic paper by Peter Miller entitled "Recursive Make Considered Harmful" ...

Anyway, I recently ran across a bunch of webpages that examined or revisited the issue. I thought several of them were worth sharing, so here they are:

• Recursive versus Non-recursive Makefile architectures benchmark
• Recursive Make isn't all that bad
• "Recursive Make Considered Harmful" Revisited
• Recursive Make Reloaded
• Implementing non-recursive make
• Non-recursive make for Linux kernel
• Non-recursive Automake
• Makepp manual pages on recursive make in legacy makefiles and problems associated with recursive makes

BOOK REVIEW: Code Craft

Nostarch Press recently published the book Code Craft: The Practice of Writing Excellent Code by Pete Goodelife.

I have to say the book looks pretty "excellent" itself. It may even become a new classic, replacing the old classic "Writing Solid Code" by Steve MacGuire. And if Steve McConnell hadn't recently updated his even more classic "Code Complete" with a 2nd edition, I might even put Code Craft on a par with that. It's that good!

It's not just about programming & design either. Like Code Complete it covers pretty much all of "software construction." It has some good stuff about build, integration, test, source-control, and more.

About my only pet peeve is that in the "Answers and Discussion" section it talks about recursive make versus inclusive make schemes. It has a pretty good discussion, but I couldn't find any reference to the classic paper by Peter Miller entitled "Recursive Make Considered Harmful". That kind of bothered me because I don't think there's any good excuse for it. It also made me wonder if there were some other places I didn't know about where appropriate references/citations were missed or neglected. (It's not severe enough to make me recommend the book any less highly though!)

I would probably put Code Craft on the "REQUIRED READING" list for any relatively new professional programmer, and have them read it just before before reading Code Complete.

TEA-Time - a metric to elicit TDD behavior?

I've been thinking about a metric that might elicit Test-Driven behaviors in my organization. As a first step to TDD, we definitely want folks to create automated tests as much as feasible and execute them frequently. Once they get that, I've been thinking about what sort of metric might encourage them to actually work in short, test-driven cycles, where requirements are elaborated test-by-test (given a use-case or story, write the first test, write the code to pass the test, refactor, rinse-lather-repeat).

Some of these folks are very much ingrained in a systems engineering V-model lifecycle that does a lot of big-requirements up-front. So ensuring they work to automate tests and execute them frequently isn't enough to enourage them to use an interative approach of fine-grained TDD-style elaboration. An idea I had for what to measure is something I chose to call Test-Execution Availability Time, or TEA-Time (I figure if nothing else, my friends in the U.K will like the name :-).

As proposed, Test-Execution Availability Time (or TEA-Time) would be defined as the mean time between when a system requirement description is first baselined, and the time at which a "sufficient" number of automated tests for the requirement were implemented and ready (available) to be executed.

I was thinking that if a group was measuring this and wanted to behave in a way that minimized TEA-Time, it might encourage them to elaborate requirements in an iterative and incremental fashion, in smaller and smaller "functional slices". One thing I'm not sure of is what "a sufficient number of automated tests" should be in the above.

Any thoughts or comments?

Codeline Flow, Availability and Throughput

There has been an interesting discussion on codeline build+commit contention on the XP yahoogroup initiated by Jay Flowers' post about a proposed build contention equation ...

The basic problem is that there have been some commit contention issues where someone is ready to commit their changes, but someone else is already in the process of committing changes and is still building/testing the result to guarantee that they didnt break the codeline. So the issue isnt that they are trying to merge changes to the codeline at the same time, the issue is that there is overlap in the time-window it takes to merge+build+test (the overall integration process for "accepting" a change to the codeline).

Jay is being very agile to the extent that he wants to promote and sustain "flow" on the codeline (see my previous blog-entry on the 5 Cs of Agile SCM Codelines). He is looking at the [average] number of change-packages committed in a day, and taking into account build+test time, as well as some preparation and buffer time. Here the "buffer time" is to help reduce contention. It makes me think of the "buffer" in the Drum-Buffer-Rope strategy of critical-chain project management (CCPM) and theory-of-constraints (TOC).

Several interesting concepts were mentioned that seem to be closely related (and useful):

• The concept of Takt time, from lean production


• Also from Lean production, the notions of process-batches and transfer-batches (especially batch processing-time versus batch transfer-time), along with the concept of single-piece flow


• The concepts and measures of system availability, reliability and survivability for codelines

If we regard a codeline as a production system, its availability to the team is a critical resource. If the codeline is unavailable, it represents a "network outage" and critical block/bottleneck of the flow of value through the system. This relates to the above as follows:

• Throughput of the codeline is the [average] number of change "transactions" per unit of time. In this case we'll use hours or days. So the number of change-tasks committed per day or per hour is the throughput (note that the "value" associated with each change is not part of the equation, just the rate at which changes flow thru the system).


• Process Batch-size is all the changes made for a single change-task to "commit" and ...
• Transfer Batch-size would be the number of change-tasks we allow to be queued-up (submitted) prior to merging+building+testing the result. In this case, Jay is targeting a one change-task per commit (which is basically attempting single-piece flow).


• Processing-time is average duration of a development-task form the time it begins up until it is ready-to-commit. And ...
• Transfer-time is the time it takes to transfer (merge) and then verify (build+test) the result.


• Takt time in this case would regard the development as the "customers" and would be (if I understand it correctly) the [average] number of changes the team can complete during a given day/hour if they didnt have to wait-around for someone else's changes to be committed.


• System outage would occur if the codeline/build is broken. It could also be unavailable for other reasons, like if corresponding network or hardware of version-control tool was "down", but for now let's just assume that outages are due to failure of the codeline to build and/or pass its tests (we can call these "breakages" rather than "outages" :-)


• MTTR (Mean-time to repair) is the average time to fix codeline "breakage," and ...
• MTBF (Mean-time before failure) is the average time between "breakages" of the codeline

Note that if full builds (rather than incremental builds) are used for verifying commits, then build-time is independent of the number of changes. Also note that it might be useful to capture the [average] number of people blocked by a "breakage," as well as the number of people recruited (and total effort expended) to fix it. That will helps us determine the severity (cost) of the breakage, and whether or not we're better off trying to have the whole team try to fix it, or just one person (ostensibly the person who broke it), or somewhere in between (maybe just the set of folks who are blocked).

Anyway, it's an interesting service-model of codeline availability and reliability for optimizing the throughput of codeline changes and maximizing collaborative "flow."

Has anyone ever captured these kinds of measures and calculations before? How did you decide the desired commit-frequency and how did you minimize build+test times? Did you resort to using incremental builds or testing?

I think that giving developers a repeatable way of doing a private development build in their workspace, even if its only incremental building+testing, gives developers a safe way to fail early+fast prior to commiting their changes, while sustaining flow.

I don't particularly care for the practice "build-breaker fixes build-breakage." At the very least I think everybody who is blocked should probably try to help (unless the number of people blocked is more than recommended size of a single team), and I'm sure the person who broke the build probably feels bad enough for causing the blockage (maybe even more so if multiple people help fix it). I think the build-breaker should certainly be a primary contributor to fixing the build and may be most familiar with the offending code, but they may need some help too, as they might not be as familiar with why/how the breakage happened in the first place since it slipped past them (unless of course it was "the stupid stuff" - which I suppose happens quite a bit :-)

So is anyone out their measuring serviceability, availability, reliability of their codelines? Are any of you using these other concepts to help balance the load on the codeline and maximize its throughput? I think that same of the more recent build automation tools (BuildForge, Maven, MS Build + TeamSystem, ParaBuild, etc.) on the market these days could help capture this kind of data fairly inobtrusively (except for maybe MTTR, and the number of people blocked and people+effort needed to effect the repair).

The 5C's of Agile SCM

Lean has it's 5S technique. And while Im certain there's a way to translate those into SCM terms (which I may try and do someday, if someone hasn't already), I'm thinking about five important C-words for Agile SCM:

• Correctness -- the property that the current configuration of the codeline executes correctly and passes its tests.


• Consistency -- the property that the current configuration of the codeline builds correctly


• Completeness -- the property that the curent configuration contains all that it should, builds all that it should, and tests all that it should


• Cadence -- the property that the codeline has a regular rhythm/heartbeat/pulse that represents a healthy flow of progress (and creates a new resulting "current configuration" every time a new change is commited, integrated, and "promoted")


• Collaboration -- the property that the balance of the above achieves a productive and sustainable degree of collaboration that serves as the source of value-generation

I think that the above represents all the properties that need to be present to a significant degree in order for the codeline to achieve smooth flow and accumulate increasing business value at a steady rate.

Am I missing anything? What about Concordance (via audits or with stakeholders)? Or Customer? Content? Context? (dare I use the word "Control"?)

Pragmatic Multi-Variant Management

I had a rather lengthy post on this subject on the Pragmatic Programming Yahoo group ...

My advice as a CM guy is you do NOT want to use branches or branching to solve this problem. If you have to manage/support multiple "configurations" of functionality for multiple markets/customers, branching is just about the worst way to do it (and this is coming from someone who is an advocate of branching, when done the right way for the right reasons).

The issue is likely to be one of "Binding Time". In your case, you would prefer the binding-time to be either at build-time (such as conditional compilation or linking), or release-engineering time (packaging up the "right" sets of files, including configuration files, for distributing to a customer), install/upgrade-time, or run-time.

One of the prefered ways to do this is with Business-Rules; particularly when it comes to decisions of "variable" policies and/or functionality. With GUI's depending on the kind of variation, you might resort to either conditional compilation or else simply creating separate source-files (instead of branching the same file).

There were some substantial discussions on this topic on CMCrossroads forums that yielded many practical insights and further resources. I recommend them:

• CM for product variations
• Branching or using #ifdef?

fantamango77 wrote:

I can say I tried out different strategies in earlier projects already. But not with such a big project. And none of the ways I took made me happy. It always ended up in a kind of hell: Configuration hell, branching hell, inheritance hell.

Yes - and some of those "circles" of h*ll are far worse than others when you look at the overall costs and effort. The bottom-line is that if you have to support multiple "variants" rather than a single evolving "line", you are adding complexity, and there is no way you are going to be able to sweep it under the rug or make it go away.

So it all comes down to which techniques and strategies in which "dimensions" of the project/product will prove most effective at minimizing and managing dependencies, effort and impact by most effectively allowing you to leverage proven principles such as encapsulation, cohesion, modularity, abstraction, etc. in the most efficient ways.

Think about what aspects or dimensions of your project/product are required to be "variable" in order for you to support multiple variants. Do your "variants" need to differ ...

• in functional/behavioral dimensions
• along organizational boundaries
• along multiple platforms/environments
• along temporal (evolution) dimensions
• along project dimensions

Figure out which one or two of these are the primary "dimensions" of variability you need to support. Then find the set of mechanisms and techniques that apply to it.

For example, if you need to allow variability primarily along functional and environmental "dimensions", then which of those "dimensions" does version branching operate within? Version branching operates primarily within the space of evolution/time (concurrent, parallel, and distributed development).

So temporally-based techniques are not going to be best suited to handling variation in the behavioral or environmental dimensions, as the isolation/insulation they provide does not most effectively minimize, localize or encapsulate the kinds of dependencies in the non-time-based aspects of the system.

Differences in policy and/or mechanism are typically best handled using a business-rules approach to deliver a single codebase with multiple possible configurations of rules and rule-settings.

Differences in platforms are best handled by well known design and architecture patterns like Wrapper-Facade, and numerous patterns from the Gang-of-Four design patterns book.

Differences in behavior may be best handled by functional/feature selection and deselection "design patterns" like Configurator, to enable or disable features and/or services at post-development binding-times.

Inheritance may be useful in some cases, if the type of configuration needed really does fit a single hierarchical model of increasing specialization. In other cases, an aspect-oriented approach might be better.

Also think about the following in terms of what needs to "vary" and what needs to stay the same:

• Interface -vs- Implementation -vs- Integration
• Container -vs- Content -vs- Context

This kind of commonality and variability analysis helps isolate the fundamental dimensions or aspects of variation that need to apply to your project. If something needs to be able to vary while something else doesnt, then "encapsulate the thing that varies" using techniques that separate interface from implementation (or implementation from integration, or etc.) in ways that "keep it [structure] shy, DRY, and tell the other guy."

You might end up using a combination of strategies depending on the different aspects of variation you require and the "dimension" in which each one operates.

CMCrossroads articles on FDD and Situational Code Ownership

The following two articles of mine appear in the April 2006 issue of CM Crossroads Journal (the month's theme is "Agile Development Practices"):

• Feature-Driven Development - an Agile Alternative to Extreme Programming


• Situational Code Ownership: Dynamically Balancing Individual -vs- Collective Ownership

If parts of them look familiar it's because these articles evolved out of multiple entries from this blog over the past year :-)

The more I look at FDD, the more I really like it as an agile method suitable for a large projects and companies, especially those striving for CMM/CMMI. I also really like the work David Anderson has done tying FDD together with Lean, TOC, and SixSigma.

I'd be real interested in any work on melding FDD together with many of the project management practices of Scrum, and some of the programming practices of XP (e.g., continuous integration, TDD, collective ownership, and refactoring).

Extreme Traceability

I gave the following response in a March 24 posting to the extreme programming list on the subject of XP-style traceability:

dsrkkk wrote:

Whatever process we use, we need to track requirements, user stories to design and test cases. The traceability provides obviously many benefits. Why don't we automate traceability? How can we humanly track these complex relationships? If we do manually, we may miss something.

I responded . . .

The less you work in a waterfallish-way, and the more you work in an agile fashion with very short feedback loops, the less necessary it becomes to make additional efforts to track/trace requirements.

If I first do lots of requirements, then lots of design, then lots of code, etc., I have to "put the pieces together." The task I performed to write requirements was different from the one that did the design which was different from the one that did code, tests, etc.

If I work in very short cycles (particularly using test-driven development), then an individual development task looks something like:

• write a single test
• write the code to pass the test and no more
• refactor the code
• commit my changes (Note I might commit my changes before refactoring too).

If, when I commit my changes to the repository, I associate my "commit" with the name or id of the story the test was for, then I have a single, fine-grained change-task that went thru the complete cycle of specification, implementation/design, verification all in a matter of minutes for a single "commit" and user-story.

Working in such fine-grained full-lifecycled tasks automatically associates all the elements that were created & updated as part of the task, which in turn is associated with a user-story. Ta da!!!! Traceability comes along for the ride almost automatically.

From Extreme Locality, in the Feb 2004 "Agile Times", pp.37-40

In Agile methods, we often hear a lot about the importance of simplicity: simple design; do the simplest thing that could possibly work; simple tools; minimal documentation ... Much of the documentation and artifacts created in larger software development methods is for the sake of capturing historical knowledge: the rhyme and reasons behind why something is there, or is designed a certain way.

The desire for such information is often used to justify the need for formal traceability and additional documentation for the sake of maintainability and comprehension. Some very powerful and sophisticated tools exist to do this sort of thing. And yet, there are basic fundamental principles and simple tactics to apply that can eliminate much of this burden.

WHENCE FORMAL TRACEABILITY?
The mandate for formal traceability originated from the days of Department of Defense (DoD) development with very large systems that included both hardware and software, and encompassed many geographically dispersed teams collaborating together on different pieces of the whole system. The systems were often mission critical in that a typical “bug” might very likely result in catastrophic loss of some kind (loss of life, limb, livelihood, national security, or obscenely large sums of money/funding).

At a high level, the purpose of formal traceability was three-fold:

1. Aid project management by improving change Impact Analysis (to help estimate effort/cost, and assess risk)
   
2. Help ensure Product Conformance to requirements specs (i.e. ensure the design covers every requirement, the implementation realizes every design element and every requirement)
   
3. Help ensure Process Compliance (only the authorized individuals worked on the things [requirements, tasks, etc.] they were supposed to do)

On a typical Agile project, there is a single team of typically less than two-dozen. And that team is likely to be working with less than 10 million lines of code (probably less than 1 million). In such situations, many of the aforementioned needs for formal traceability can be satisfactorily ensured without the additional rigor and overhead of full-fledged formal requirements tracing.

Rigorous traceability isn’t always necessary for the typical Agile project, except for the conformance auditing, which some Agile methods accomplish via test-driven design (TDD). A “coach” would be responsible for process conformance via good practices and good “teaming,” but likely would not need to have any kind of formal audit (unless obligated to do so by contract or by market demand or industry standards).

Agile methodologies turn the knob up to 10 on product conformance by being close to the customer, by working on micro-sized changes/increments to ensure that minimal artifacts are produced (and hence with minimal reconciliation) and that communication feedback loops are small and tight. Fewer artifacts, better communication, pebble-sized change-tasks with frequent iterations tame the tiger of complexity!

For more then you ever wanted to know about the why&wherefore behind traceability, see The Trouble with Tracing: Traceability Dissected

Kandt's SCM Best-Practices: Tool Practices

More from the paper Software Configuration Management Principles and Best Practices, by Ronald Kirk Kandt, appearing in the Proceedings of PROFES2002, the 4th International Conference on Product-Focused Software Process Improvement, Rovanieme Finland, December 2002.

In this article, Ronald Kandt describes ten basic principles that support configuration management activities, and then goes on to describe twenty three "fundamental" practices, which are split across the categories of: Management Practices, Quality Practices, Protection Practices, and Tool Practices.

In this entry, I'll enumerate Kandt's Tool Best-Practices for SCM (in priority order, with the most important ones listed first):

Practice 19:

Check code in often

Kandt goes on to explain "This practice should be constrained when checking in code on the primary development branch. That is, developers should only check in working versions of code to a [primary] development branch."

The main reason given is to ensure against loss of change by making sure the code is in the repository. So although initially it might seem this practice is about committing in small talks (which I'm sure Kandt would approve), that doesn't appear to be what he's emphasizing. This really seems to be about frequent use of "Private Versions" and then, before doing a Task-Level Commit, making sure one does a Private Build and runs Unit Tests and Smoke Tests as part of the Codeline Policy.

In other words: "If it ain't checked-in, it don't exist!"

Practice 20:

Configuration management tools should provide patch utilities

The stated benefit here is to support incremental release/deployment and also remotely submitted changes over slow telecommunication connections.

Practice 21:

Do not work outside of managed workspaces

Seems like the "Private Workspace pattern to me

Practice 22:

Do not share workspaces

This is sort of reinforcing that the workspace should be private rather than shared. Having said that, while I agree shared workspaces (not include Pair-Programming) shouldn't usually be the norm, I have seen cases where it can work quite well.

In order for this to work, there must be an explicit "protocol" agreed upon up-front by all the contributors to decide who doing what, when, and to what (not just who is modifying which files when, but who is building what else and when) and/or how to rapidly communicate who is doing what when. See also work by Andre van der Hoek et.al. on Continuous Coordination: A New Paradigm for Collaborative Software Engineering Tools and related work on the "Palantir" project.

Practice 23:

When developing software on a branch other than the primary branch, regularly synchronize development with the development branch

This seems like mainlining (the Mainline pattern) and rebasing (a.k.a. Workspace Update). Only I would say that regularly synchronizing should apply to private workspaces/sandboxes even when they aren't using a private or task branch. The more general rule would seem to be the Continuous Update pattern.

Th-th-th-thats all from Mr. Kandt's list of 10 SCM principles and 23 SCM best-practices!

Kandt's SCM Best-Practices: Protection Practices

More from the paper Software Configuration Management Principles and Best Practices, by Ronald Kirk Kandt, appearing in the Proceedings of PROFES2002, the 4th International Conference on Product-Focused Software Process Improvement, Rovanieme Finland, December 2002.

In this article, Ronald Kandt describes ten basic principles that support configuration management activities, and then goes on to describe twenty three "fundamental" practices, which are split across the categories of: Management Practices, Quality Practices, Protection Practices, and Tool Practices.


In this entry, I'll enumerate Kandt's Protection Best-Practices for SCM (in priority order, with the most important ones listed first):

Practice 15:

Use a software system to perform configuration management functions

Also known as: "Use an SCM tool!"

Practice 16:

Repositories should exist on reliable physical storage elements

Practice 17:

Configuration management repositories should be periodically backed-up to non-volatile storage and purged of redundant or useless information

Practice 18:

Test and confirm the backup process

Is there really anything here to argue with? (I didn't think so :-)

Oh, and that #18 is one that is often overlooked. I can't tell you the number of times I've come across folks that think there stuff is safe "cuz it's backed-up," but their backup process didn't confirm that they were able to successfully read/extract the data that was archived.

Next up, we'll look at what Kandt identifies as Tool practices in his list of 23 SCM best-practices.

Kandt's SCM Best-Practices: Quality Practices

More from the paper Software Configuration Management Principles and Best Practices, by Ronald Kirk Kandt, appearing in the Proceedings of PROFES2002, the 4th International Conference on Product-Focused Software Process Improvement, Rovanieme Finland, December 2002.

In this article, Ronald Kandt describes ten basic principles that support configuration management activities, and then goes on to describe twenty three "fundamental" practices, which are split across the categories of: Management Practices, Quality Practices, Protection Practices, and Tool Practices.


In this entry, I'll enumerate Kandt's Quality Best-Practices for SCM (in priority order, with the most important ones listed first):

Practice 8:

All source artifacts should be under configuration control

Practice 9:

Use a Change-Control Board (CCB)

Practice 10:

Build software on a regular, preferably daily, basis, followed by invocations of regression test suites

Practice 11:

Document identified software defects

Practice 12:

Software artifacts that comprise a release should adhere to defined acceptance criteria

Practice 13:

Each software release should be regression tested before the test organization receives it

Practice 14:

Apply defect repairs to every applicable release or ongoing development effort

Most of folks in the "Agile camp" and in the "CM camp" would probably consider most of these to be "no brainers." The ones that Agilists might pick nits with are 8, 9, 11 and 14.

Control Contrarians and Wooden "Boards"

For 8 and 9, I don't think you'll find any agile folks recommending against the use of a version control system/repository. They would likely take issue with the appropriate meaning of "control." The words "control" and "change control" often set off sirens and red-flags for many agilists. And with good reason - they all too often see control attempted in a way that stifles developers and imposes highly restrictive waiting and redundancy for authorization/permission to do things; and they often see it executed as a means of preventing change instead of embracing it (see The Unchangeable Rules of Software Change).

Agilists also don't like the term CCB. Not only does the word "control" raise hackles (as already mentioned), but the term "Board" doesn't mesh very well with Agile values and perspectives on the whole concept of "team": a "board" conjures images of people isolated from the day-to-day workings and workers of the project. In reality, iteration planning meetings basically fill the CCB function for most agile projects because the iteration is usually small enough that there just isn't time to introduce new requirements within the iteration's timebox, so it's usually deferred to the next iteration.

Bugbases and Human Faces

There are many agilists who will rail against using a change/defect tracking tool. They say things like: there shouldn't be enough defects to warrant a bugbase (as opposed to a spreadsheet); rather than documenting and describing them in a database, we should just go fix 'em instead; index cards are a better for recording the bare essentials and promoting conversational dialogue and two-way face-to-face communication; tracking systems dehumanize communication and are too easily misused to the effect of hindering rather than facilitating dialogue and collaboration.

I understand all of these remarks and concerns. And while they all raise valid points, my own position is different. I consider a basic defect/issue/enhancement tracking (DIET) system to be every bit as essential as a version control tool. I still use index cards as a means of initiating dialogue and eliciting/capturing resulting needs and constraints. But then I put them into the tracking tool. Maybe if my handwriting were more legible the cards would be comprehendible enough to others, but I still think it's much more useful and convenient for tracking, organizing, sorting, searching, status accounting and generating reports (even if they just get posted to a local "information radiator").

I also think information about defects should be captured in order to identify and understand possible trends and root-causes, as well as provide evidence and history to consumers and customers (especially those requiring formal support/service-level agreements).

I do think a lot of change control implementations (and resulting tool customizations) make things harder on developers than needed, for the sake of convenience to other roles. I think that's what leaves the bitter taste in many agilists mouths and why they dislike it so much - because it holds them back and/or diverts them away from what they feel is most important: delivering value to the customer in the form of tangible, tested results. I think that's a shame because I think it doesnt' have to be that way. A few tracking tools are gaining popularity in the Agile arena, like VersionOne, and Jira.

The Monstrosity of Multiple Maintenance

Okay - I don't think that any agilists will say that a defect shouldn't be fixed in all applicable release. What they will say is that they would first do everything in their power to have one and only one mainline of development. Branching a new mainline to support a legacy release or a market/platform/project-specific variant is anathema for most agilists: it creates redundancy among code-streams (fixes have to be applied and integrated more than once) and splits the value-delivery stream into isolated streams/teams of diminished capacity.

Agilists would prefer to see a solution at a later binding time that uses design patterns of software architecture, building/releasing, licensing/distribution, & install/upgrade rather than patterns of version branching. For the most part I agree with them, but I am less wary of branching in the case of parallel development (because I know how to do it really effectively), and I am perhaps more accepting of the case of multiple releases (but I would still fight like heck against multiple variants :-)

Next up, we'll look at what Kandt identifies as Protection practices in his list of 23 SCM best-practices.

Kandt's SCM Best-Practices: Management Practices

More from the paper Software Configuration Management Principles and Best Practices, by Ronald Kirk Kandt, appearing in the Proceedings of PROFES2002, the 4th International Conference on Product-Focused Software Process Improvement, Rovanieme Finland, December 2002.

In this article, Ronald Kandt describes ten basic principles that support configuration management activities, and then goes on to describe twenty three "fundamental" practices, which are split across the categories of: Management Practices, Quality Practices, Protection Practices, and Tool Practices.


In this entry, I'll enumerate Kandt's Management Best-Practices for SCM (in priority order, with the most important ones listed first):

Practice 1:

Maintain a unique, read-only copy of each release

Also known as: create an immutable release label

Practice 2:

Control the creation, modification, and deletion of software artifacts following a defined procedure

Also known as: use version control, and agree on how you'l be doing it -- for example by identifying which SCM patterns you'll be using and their specific implementation in your project's context

Practice 3:

Create a formal approval process for requesting and approving changes

Also known as: manage change/scope, preferably by managing expectations rather than by trying to prevent change

Practice 4:

Use Change Packages

This one is more than just task-level commit, it builds on task-level-commit to provide task-based-development

Practice 5:

Use shared build processes and tools

We wrote about this in our October 2003 CM Journal article on Agile Build Management and it's March 2004 successor article on Continuous Staging

Practice 6:

A version manifest should describe each software release

This is more than just a self-identifying configuration listing of files and versions. Kandt also intends it to mean identifying the set of features, fixes, and enhancements too, as well as all open problems and issues. This is often included in the release notes for a new release. It also relates to the information necessary to satisfy a configuration audit.

Practice 7:

Segregate derived artifacts from source artifacts

Also known as: know your sources from your targets! Often times, the versioning/storage strategies used for the two may differ. (Of course, that's not the only reason to segregate them.)

Next up, we'll look at what Kandt identifies as Quality practices in his list of 23 SCM best-practices.

Kandt's SCM Principles

From the paper Software Configuration Management Principles and Best Practices, by Ronald Kirk Kandt, appearing in the Proceedings of PROFES2002, the 4th International Conference on Product-Focused Software Process Improvement, Rovanieme Finland, December 2002.

In this article, Ronald Kandt describes ten basic principles that support configuration management activities, and then goes on to describe twenty three "fundamental" practices, which are split across the categories of: Management Practices, Quality Practices, Protection Practices, and Tool Practices.


In this entry, I'll simply enumerate the principles from the article. In subsequent entries I'll list the 4 different sets of best-practices.

Kandt's Ten Basic Principles of SCM are:

Principle 1:

Protect critical data and other resources

Principle 2:

Monitor and control software development procedures and processes

Principle 3:

Automate processes and procedures when cost-effective

Principle 4:

Provide value to customers

Principle 5:

Software artifacts should have high-quality

Principle 6:

Software systems should be reliable

Principle 7:

Products should provide only necessary features, or those having high value

Principle 8:

Software systems should be maintainable

Principle 9:

Use critical resources efficiently

Principle 10:

Minimize development effort

Nothing particularly earth shattering here. A few interesting things to note:

• All of them are certainly well aligned with agility, or any sound engineering practices for that matter. But #7 and #10 seem especially well aligned with agility, and are often not emphasized enough in many CM circles.
• #10 in particular might surprise some folks, because I'm sure many developers might perceive CM as trying to do anything but minimize development effort, and may feel #10 is often treated as secondary and subordinate to #2
  

That's all well and good. Those things are easy to say "should" about. What's harder is to successfully do them all, and balance them all effectively when facing an SCM problem. It will be more interesting to see what Kandt's 23 SCM best-practices are, and how they manage to uphold these principles.

I'll also note that these principles seem somewhat different from the kind of SCM Principles I've been trying to compile. The things I'm looking for are less about SCM process goals, and more about SCM solution design (e.g., design principles for how to design or select an SCM best-practice that most effectively preserves the above goals). In this regard, I might consider most of the above to be goals more than principles (but with a few exceptions.)

Lean Principles for Branching

A recent thread on the scrumdevelopment YahooGroup about "Scrum releases and SCM" got me thinking about a set of "Agile SCM" slides I prepared, one of which tried to apply principles of lean thinking to branching and merging for version control and their relationship to some of the SCM Patterns.

That was using an earlier version of the principles when Tom and Mary had 10 or so of them. Now they've narrowed it doesnt to seven, so I figured I'd take another stab at it:

1. Eliminate Waste – Eliminate avoidable merge-propagation (multiple maintenance), duplication (long-lived variant branches), and stale code in infrequently synchronized workspaces (partially completed work)


2. Build Quality In – Maintain codeline integrity with (preferably automated) unit & integration tests and a Codeline Policy to establish a set of invariant conditions that all checkins/commits to the codeline must preserve (e.g., running and passing all the tests :-)
   


3. Amplify Learning – Facilitate frequent feedback via frequent/continuous integration and workspace update


4. Defer Commitment (Decide as late as possible) -- Branch as late as possible! Create a label to take a "snapshot" of where you MIGHT have to branch off from, but don't actually create the branch until parallelism is needed.


5. Deliver Fast (Deliver as fast as possible) -- complete and commit change-tasks and short-lived branches (such as task-branches, private-branches, and release-prep branches) as early as possible


6. Respect People (Decide as low as possible) -- let developers reconcile merges and commit their own changes (as opposed to some "dedicated integrator/builder")


7. Optimize the "Whole" -- when/if branches are created, use the Mainline pattern to maintain a "leaner" and more manageable branching structure

Did I get it right? Did I miss anything?

Interface Segregation and Configuration Promotion

I've been thinking more about the Interface Segregation Principle (abbreviated as "ISP") from (Uncle) Bob Martin's Principles of Object-Oriented Design.

The "short version" of ISP in the initial article states that:
=> "Clients should NOT be forced to depend on interfaces that they do not use."

The summary of ISP in Uncle Bob's website says it differently:
=> "Make fine grained interfaces that are client specific."

In previous blog-entries, I've wondered how this might correctly translate into an SCM principle (if at all).

• In Change-Packaging Principles, I wondered if maybe it corresponds to change-segregation or incremental integration: Make fine-grained incremental changes that are behavior-specific. (i.e., partition your task into separately verifiable/testable yet minimal increments of behavior.)


• On the scm-patterns list I wondered if maybe it corresponds to composite baselines: composing baselines of other, more fine-grained baselines


• Now I'm thinking maybe it corresponds to promotion lifecycle modeling and defining the promotion-levels in a promotion-lifecycle of a configuration-item (e.g., a build).

Why am I thinking this?

I guess I'm trying to go back to the basis of my means of comparison: configurations (and hence baselines) as "objects." If a configuration is an object, then what is an interface of a configuration, and what is a fine-grained interface (or "service")?

If I am thinking in terms of configuration building, then the interface for building the object (configuration) is the equivalent of Make/ANT "methods" and targets for a given item: (e.g., standard make targets like "clean", "all", "doc", "dist", and certain standard conventions for makeflags). That is certainly a plausible translation.

But if I am thinking in terms of baselining and supporting CM-mandated needs for things like reproducibility, repeatability, traceability, from the perspective of the folks who "consume" the baseline (it's clients), then maybe the different consumers of a baseline need different interfaces.

If those consumers end up each "consuming" the baseline at different times in the development lifecycle (e.g., coding, building, testing, etc.) then perhaps that defines what the promotion model and promotion levels should be for that configuration.

What if they aren't at different times in the lifecycle? What if they are at the same time?

Then I guess it matters if the different consumers are interested in the same elements of the baseline. If they're not, maybe that identifies a need for composite baseline.

What if they aren't at different times and aren't for different elements, but rather the same sets of elements?

Then maybe that identifies different purposes (and services) needed by different consumers for the same configuration at the same time. Building -versus- Coding might be one such example. Would branching -versus- labeling be another? (i.e. "services" provided by a configuration as represented by a "label" as opposed to by a "codeline", or a "workspace"?)

What if no one of these is the "right" interpretation? What if it's ALL of them?

Then that would be very interesting indeed. If the result encompassed the interfaces/services provided by different Promotion-Levels, Make/ANT-targets, branch -vs- label -vs- workspace, then I don't even know what I would call such a principle. I might have to call it something like the Configuration ISP, or the Representation separation principle, or the manifestation segregation principle, or ....

What, if anything, do YOU think the ISP might mean when applied to Software CM and software configurations as represented by a build/label/codeline/workspace?

Subversion plus Trac gives SubTraction

Here's a bit of a "plug" for some open source SCM tool offerrings ...

For those CVS users who don't already know about Subversion I urge you to take a look. Subversion was designed to be a next-generation replacement for CVS that has a lot of the same basic syntax and development model while fixing or updating most of its well known shortcomings.

Another spiffy open-source project that integrates with both CVS and Subversion is Trac, which provides simple but powerful defect/issue/enhancement tracking (DIET) using a Wiki-web interface, and readily integrates with both CVS and Subversion to add collaborative, low-friction request/activity tracking to your version control and can be used to track change-sets in the version control tool and associate them with change-tasks/requests in the tracking tool.

Using Trac with Subversion can help "subtract" a lot of the tedium of traceability from your day-to-day work and give more "traction" to your development efforts. So, in a way, Subversion plus Trac gives SubTraction :-)