[…] on any non-trivial project (more than about 1 week of coding or more than one programmer), if you don’t have a spec, you will always spend more time and create lower quality code. ~ Joel Spolsky

A specification is an efficient way to communicate your work with others and ensure that you have consensus on the design before progressing with its implementation.

Expected duration
2 hours per team member
Points
30 points

Assignment

Each team is responsible for collaborating on a single specification. Completing the specification early in the sprint (e.g., by the conclusion of the first week) is recommended to minimize the amount of rework required if substantial changes are requested. After its initial submission, each specification should be reviewed and (eventually) approved by others on the team, looking for areas of ambiguity, incompleteness, inconsistency, etc. Implicitly this means that 1-2 team members should draft the initial version of the specification and further development of the specification is handled through comments on a pull request. Following this review and any required changes, the specification serves as a “contract” for what will be implemented. Later changes must be approved as part of the requirements management process.

When you write the specification, exhaustive detail is not necessary, but someone else should be able to implement the feature if required.

You must use the provided template for the specification. Add your specification to the repository’s doc/specs directory. The specification should be written using reStructuredText (RST), which is a lightweight markup language for text documents. The file name for your specification should describe your work and use dashes between words. For example, if adding support for single sign-on using OAuth, the file name for your specification might be add-oauth-support.rst, or if refactoring existing back-end code, the file name might be refactor-database-interface.rst.

The specification template is derived from those used by OpenStack. As an open source project, the quality of OpenStack’s specifications varies, but those of the compute service are generally well-written. If struggling to understand what amount of detail to include in the specification, one approach is to review a half-dozen or so OpenStack specifications to get a feel for what is required to manage a large open source project. (Hint: More information is generally better, and although exhaustive detail is neither required nor appropriate, always trend toward including more information whenever in doubt.) A more entertaining resource is Joel Spolsky’s series “Painless Functional Specifications,” which addresses this topic humorously and pragmatically.

Template

======================
Specification Template
======================

The introductory paragraph should succinctly describe the problem and the
proposed solution. Extensive technical details should not be provided in this
paragraph; the description should be understandable by others, even if they
are not familiar with the larger system.

General guidance for this specification:

* Replace the existing text with the appropriate details for the feature to
  be implemented. Don't forget to replace the title of the specification with
  the name of the feature. Do not delete any sections of this template.

* This document is formatted via reStructuredText [RST]_. Anyone who is not
  familiar with reStructuredText markup may benefit from its quick reference
  guide [QuickRST]_.

* Please wrap lines at 79 characters.

Problem Description
===================

What is the problem? This section provides a detailed description of the
problem.

Requirements
------------

What are the functional and non-function requirements that express the desired
behavior of the system?

Use Cases
---------

A *use case*, at a high level, is a story about an observable interaction (a
"thread of usage") between the system and the environment. Each story is
described from the point of view of an actor that interacts with the system
in some way.

Each feature must include at least one use case that answers the following
questions:

* Who is the primary actor and the secondary actor(s)?
* What are the actors' goals?
* What preconditions exist before the story begins and postconditions after the
  story ends?
* What main tasks or functions are performed by the actor(s)?
* What variations in the actors' interactions are possible (e.g., exceptions)?

Proposed Change
===============

This section describes how the requirements will be satisfied by the software
system. Considerable detail should be provided -- enough that someone else
could implement this feature.

If this feature is part of a larger effort, include at least one paragraph
describing how this feature fits into the larger system. Be sure to include
the scope of this feature so it is clear where this effort ends. Very large
features may be broken up into multiple pieces and implemented separately,
in which case it is necessary to clearly delineate where each piece ends.

Alternatives
------------

What other options exist to satisfy the requirements? Why is the proposed
approach better than those options?

Testing
=======

What is the test plan? That is, how will this change be tested? Are there
specific test cases to guard against expected faults?

Provide a detailed rationale if some portions of the proposed change are not
testable or no specific test cases will accompany the implementation.

Documentation
=============

What documentation should accompany this change -- e.g., in-line comments in
the source code or user manuals? Be sure to identify the target audience for
various forms of documentation if it isn't obvious from the context (e.g.,
source code comments are typically intended for developers).

Implementation
==============

Work Items
----------

If this feature will be implemented in phases (and most features should be!),
enumerate the individual pieces that will collectively implement the proposed
change. Work items may be supported by different people, but they also provide
a rough timeline for the proposed feature.

Assignee(s)
-----------

Who is responsible for implementing this specification? If the prior work items
require multiple contributors, please designate the "lead" who will oversee all
aspects of the work and other contributors, including those contributors'
specific contributions.

Primary assignee:
  Name and Email

Other contributors:
  Name and Email

References
==========

Please include any relevant references that are related to the problem or the
proposed change. The references should supplement the material already in this
specification -- i.e., the specification must make sense even if the references
are not available.

.. [RST] David Goodger, "reStructuredText Markup Specification," May 2016.
   Online: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

.. [QuickRST] Quick reStructuredText. Online:
   http://docutils.sourceforge.net/docs/user/rst/quickref.html

Submission

To “submit” your specification, create a pull request in GitHub.

The pull request triggers a review of the specification so that you have feedback and the opportunity to improve the specification, ideally before you complete substantial work on the implementation. Expect to iterate on the specification, using the feedback to improve the initial version – it’s rare for any software engineering artifact to be “right” the first time.

Grading

The specification will be graded at the end of the sprint and is based on its final version (i.e., incorporating all updates from the review process). If the pull request has been merged, then you will earn full credit for the specification. Conversely, a pull request with unaddressed comments will earn a low score because there are remaining opportunities for improvement.

Your goal should be to address the feedback as thoroughly and as quickly as possible to ensure that the specification is approved and earns full credit for this assignment. Take advantage of the iterative review process – the quality bar is high precisely because that’s what expected in real software projects.

Rubric

The following grading rubric will be used for this assignment:

Superb (100%)
Pull request approved / merged
Proficient (80%)
Trivial issues only (e.g., formatting and clarification to wording, but no content changes)
Competent (50%)
Major issue that requires resolution and consequent significant revision, or multiple minor issues that require revision
Novice (30%)
Multiple major issues requiring revision of multiple sections
Missing (0%)