A11y All the Things

PenultimateWidgets has decided that all new development of user interfaces must support accessibility, both web and desktop. Because this is a new initiative for developers, architects fear they will forget to do this and thus want safeguards.

  • Categories: atomic, triggered
  • Requirements:
    • all new web development must support accessibility
    • all new Java Swing development must support accessibility
  • Additional Context:
    • all UX is in either Java Swing or Javascript

Audit the Accounting

PenultimateWidgets has been a Bad Company (cheating on some complex accounting rules), but they have reformed their ways and paid their penalties. Now, however, as part of the settlement, they agree to put auditing measures in place around code that handles accounting rules. State auditors come once a quarter to look everything over, but PenultimateWidgets has found it too much of a chore to delay preparation until near audit time; they want a more automated way to verify things.

  • Categories: atomic, triggered and manual
  • Requirements:
    • all code that affects accounting must be limited to a certain set of packages/namespaces
    • code in those packages must be flagged as affected when changes occur
  • Additional Context:
    • the team uses git for version control

Avoid Complex Code

PenultimateWidgets has recently hired many new graduates and interns. During code reviews and pairing, more senior developers notice a tendency towards overly complex code, including long methods and classes. They need fitness function(s) to control this.

  • Categories: atomic, triggered
  • Requirements:
    • validate that methods do not become overly long
    • validate that classes do not carry too much responsibility
    • validate that classes have good cohesion
  • Additional Context:
    • PenultimateWidgets will pay for tools if necessary
    • PenultimateWidgets is willing to slow down velocity to improve code quality

Break On Upgrade

PenultimateWidgets builds a number of applications in Ruby on Rails, which has an active release schedule. Occasionally, developers really want a feature that appears in version X+1, where PenultimateWidgets is currently on version X. To acquire the desired functionality, developers back-port the new features from X + 1 into X. However, when PenultimateWidgets finally does upgrade to X + 1, the back ported features are almost certain to break because of incompatibilities.

  • Categories: atomic, triggered, temporal
  • Requirements:
    • Make sure that all back-ported features do not survive the upgrade to the next version.
  • Additional Context:
    • PenultimateWidgets Ruby on Rails applications all have excellent test suites and deployment pipelines.

Configure Some of the Things All of the Time

PenultimateWidgets has been burned in the past by having hard-coded constants in several places in their code base, governing both business cases (thresholds, maximums, etc.) and operational concerns. Architects need a way to prevent developers from accidentally hard-coding critical values.

  • Categories: atomic, triggered
  • Requirements:
    • architects define a list of dynamic values that should always pulled from a configuration file, not hard coded.
  • Additional Context:
    • all the teams use deployment pipelines and a declarative language to provision infrastructure

Cycle Time Guard

PenultimateWidgets has entered an extremely competitive market, with a startup running popular flash promotions. The marketing department has committed to keeping up with PenultimateWidgets own aggressive marketing campaign, which requires development teams to be able to deliver changes to the promotion pages within an hour. Thus, they want a guarantee that changes can always take place within an hour.

  • Categories: atomic, triggered
  • Requirements:
    • changes to marketing pages (and subpages) must take place within an hour of analyst checking copy into the CMS
    • provide weekly trend lines for deployment times
  • Additional Context:
    • the marketing application is a monolith but it has good component separation

Debug All the Things

PenultimateWidgets wants to ensure that both Java and Javascript applications support remote debugging in the development environment to aid in faster customer support resolution.

  • Categories: atomic, continuous
  • Requirements:
    • All Java applications deployed in the development and QA environments must have remote debugging enabled
    • Javascript deployed in the development and QA environments must be debuggable
  • Additional Context:
    • all projects run a deployment pipeline

Degrade Gracefully

PenultimateWidgets is proud of how popular their website has become and want to make sure the site performance degrades gracefully as scale increases.

  • Categories: holistic, continuous
  • Requirements:
    • the enterprise architects have defined thresholds for acceptable performance degradation under scale, and the architecture should maintain performance and scale within those parameters
  • Additional Context:
    • the architecture support good incremental change and modern DevOps practices

Depend on Dependencies

PenultimateWidgets has recently been burned by a Maven update that broke several applications yet wasn't detected until production. Architects and business people want to make sure this doesn't happen again.

  • Categories: atomic, triggered, manual
  • Requirements:
    • Make sure that no dependency updates break functionality past the developers' staging environment.
  • Additional Context:
    • All affected projects use Java, Ruby, and Javascript.

Deploy All The Things

PenultimateWidgets has gotten tired of each application requiring an elaborate environment setup to deploy and run, and has decided that all new applications must be deployed within Docker containers. The PenultimateWidgets architects want to ensure that all applications follow the same standard deployment guidelines.

  • Categories: atomic, continuous
  • Requirements:
    • Each application deployment must occur within a Docker container
  • Additional Context:
    • All the applications are containerizable, some with great effort.

Deterministic Distributability

PenultimateWidgets has been burned in the past by hard-coded strings in applications that tie applications to a particular data center location. They want to ensure this doesn't happen in the future.

  • Categories: atomic, triggered
  • Requirements:
    • Ensure that no data center location is embedded within an application
  • Additional Context:
    • PenultimateWidgets uses several different data centers, distributed geographically.

Dire Deltas

PenultimateWidgets developers have developed a bad habit of keeping files checked out for days or weeks at a time, preventing continuous integration. As part of their attempt to improve engineering practices overall, the enterprise architects at PenultimateWidgets encourage frequent check-ins with corresponding good test coverage.

  • Categories: atomic, process
  • Requirements:
    • All check-ins must contain less than 1000 lines of code
    • The ratio of test code to source code should be at least 0.75:1
  • Additional Context:
    • All projects now use a continuous integration server
    • All projects use the same directory structure, with well partitioned tests

Discover All The Things

PenultimateWidgets publishes an API for third-party, business-to-business integrations. To make it easier for clients to consume their services, they have instituted a convention that every endpoint delivers a documentation string when called with the additional parameter '&docs=true'. PenultimateWidgets architects want to ensure that all published endpoints include this documentation string.

  • Categories: atomic, continuous
  • Requirements:
    • Every published external endpoint must include appropriate documentation strings when invoked.
  • Additional Context:
    • Not all projects at PenultimateWidgets are running a deployment pipeline yet.

Doc Sync With API

PenultimateWidgets publishes an API for external vendors to check on order status, availability, and other B2B perqs. However, the external partners rely on the documentation of the API, which sometimes becomes outdated when developers add new functionality. The PenultimateWidgets architects want to ensure that documentation is always up to date, especially method signatures and data formats.

  • Categories: atomic, triggered
  • Requirements:
    • Documentation must match current code.
  • Additional Context:
    • Documentation is generated from code, so method signatures should be up to date. However, developers must make sure that descriptions for each method parameter has proper documentation.
    • Ensure that the version posted on the public website matches the current released version.

Elasticity of Microservices

PenultimateWidgets utilizes a microservices architecture and want to ensure that as new requests appear that the architecture elastically scales.

  • Categories: atomic, triggered
  • Requirements:
    • For microservices determined to need it, they should support elastic scale
    • As the number of requests excedes the defined threshold, the service discovery tool creates more instances and dispatches requests
  • Additional Context:
    • PenultimateWidgets microservices use a common service template that handles discovery

Install All The Things

PenultimateWidgets distributes a desktop application to select clients that facilitates coordination between business partners. The application is written in C#, using .NET desktop libraries. In the past, PenultimateWidgets has exhibited problems with the installer not working correctly for some edge cases, and they want to ensure that their clients have a good installation experience.

  • Categories: atomic, triggered
  • Requirements:
    • Make sure that the desktop installation installs correctly each time developers make a change in the code base.
  • Additional Context:

    Legality of Open Source Libraries

    PenultimateWidgets lawyers became worried about the license terms of the open source libraries PenultimateWidgets used--they wanted to make sure they weren't allowing any viral licenses. They did the initial check of the licenses, but then one asked the developers: what happens if one of the frameworks changes their license?

    • Categories: atomic, triggered, manual
    • Requirements:
      • make sure that open source licenses do not change in undesirable ways
    • Additional Context:
      • all the libraries PenultimateWidgets uses have clear license terms within the distributions

    Maintain the Mock

    PenultimateWidgets has started experimenting with flashing the chips on their 'smart' widgets during the manufacturing process, allowing them to make changes in hardware-based code more easily and quickly. However, they must make sure that the mock version of the hardware API the developers use is always up to date with the real API.

    • Categories: atomic, triggered
    • Requirements:
      • Ensure that the mock API always matches method names, parameters, and types
    • Additional Context:
      • A mock testing framework exists that replicates the hardware API, but it must be maintained by the hardware team.

    Maintaining Good Throughput

    PenultimateWidgets is proud of how popular their website has become and want to make sure they maintain good throughput: a combination of performance and scalability.

    • Categories: holistic, continuous
    • Requirements:
      • the enterprise architects have defined thresholds for acceptable performance degradation under scale, and the architecture should maintain performance and scale within those parameters
    • Additional Context:
      • the architecture support good incremental change and modern DevOps practices

    Make Sure New Really Replaces Old

    PenultimateWidgets legacy accounting system grew over many years, with arcane business rules scattered in many places--no one really understands how everything works anymore. They have been working for several years on replacing the accounting system, but worry that the new system cannot replicate the byzantine business rules that their clients have come to depend upon.

    • Categories: holistic, triggered
    • Requirements:
      • make sure all accounting transactions for invoicing, discounting, and incentives show parity in results across the old and new system
    • Additional Context:
      • the legacy accounting system has a few spotty unit tests but no good coverage and no other testing. The unit test that exist are pootly maintained and unreliable.

    Monitor All The Things

    PenultimateWidgets wants to ensure that Java and .NET applications support monitoring.

    • Categories: atomic, continuous
    • Requirements:
      • All Java applications in all environments must support monitoring by the chosen tool
    • Additional Context:
      • all projects run a deployment pipeline
      • the deployment pipeline uses automated machine provisioning for all environments

    No More View Models

    PenultimateWidgets has a group of developers who cut their teeth on mainframe programming, where all work is done via a terminal. They have (mostly) switched to modern web development, but architects find that they often create models and workflows directly in web pages rather than support a cleaner MVC separation, and they would like to discourage this behavior.

    • Categories: atomic, triggered
    • Requirements:
      • no model or controller code may appear in view pages
    • Additional Context:
      • developers are using Java or .NET on the server side

    Replace the Crufty Core

    PenultimateWidgets built a network scanning tool many, many years ago to look for suspicious activity at the network packet level. To achieve the proper performance, the code was written and has been maintained in increasingly complex C code. PenultimateWidgets needs to replace the code but is nervous about introducing bugs and/or harming performance or throughput.

    • Categories: atomic, continuous
    • Requirements:
      • The preference is to replace C altogether with a more modern language such as Java or Go.
      • The new solution must replicate the behavior of the old rules, and allow new rules to be written in the improved language.
    • Additional Context:
      • C was chosen 10 years ago because it was the only choice that could possibly deliver the required performance.

    Respond Responsibly

    PenultimateWidgets business analysts are worried about one of their key competitors, who has a very fast website. PenultimateWidgets website has traditionally not featured speed; they want to ensure that the responsiveness doesn't get worse.

    • Categories: holistic, triggered
    • Requirements:
      • Establish a responsiveness service-level agreement for each major page
      • Ensure that no page drops below their threshold
    • Additional Context:
      • All PenultimateWidgets websites are structured well enough to allow some degree of automated testing.

    Sell The Platform

    PenultimateWidgets is in the process of rebuilding their core platform, incorporating some key features that will appeal to others in a similar problem space. PenultimateWidgets plans to sell their platform to other companies, but worry that the differentiating factors (such as performance, scale, and elasticity) will suffer as clients start making changes to the platform, ultimately harming PenultimateWidgets platform's reputation. How can they sell their platform and still ensure that the critically important characteristics remain unchanged?

    • Categories: triggered, holistic
    • Requirements:
      • PenultimateWidgets must ensure that clients meet the same system level agreements over a variety of architectural characteristics.
    • Additional Context:
      • PenultimateWidgets has a rich set of fitness functions and a well constructed deployment pipeline.

    Upgrade All The Things

    PenultimateWidgets has a bad habit of waiting too long to update core libraries and frameworks they depend upon for development. Waiting past several versions makes the eventual upgrade quite painful, and they have resolved to perform upgrades in a more timely manner.

    • Categories: atomic, temporal
    • Requirements:
      • When a new major version of a library or framework appears, make sure PenultimateWidgets has upgrades within 3 months.
    • Additional Context:
      • PenultimateWidgets uses a deployment pipeline for all projects.

    Zero Day Security Check

    PenultimateWidgets management has become concerned about zero-day exploits in open source libraries and has tasked the security team with coming up with a way of ensuring that projects do not use known compromised versions.

    • Categories: atomic, triggered
    • Requirements:
      • when the security team identifies a critical exploit, ensure that teams do not deploy anything with that version
    • Additional Context:
      • all PenultimateWidgets projects utilise a deployment pipeline