Specification Template

Feature Name

Name:

Affiliation:

Target/Actual Release Date/Project Milestone (delete as appropriate):

Reviewers:

GitHub Issue: #number

---

1. Introduction
2. Requirements
   1. Architectural
   2. Functional
   3. Other
3. Functional
   1. Build
   2. Configuration
   3. Run
4. Architectura
   1. CMake and Build
   2. Design Details
5. Implementation
6. Integration
7. Test Specification
8. Documentation Impact

---

Introduction

High-level description of your feature.

Things to include:

• Current situation/capabilities of the program (before feature added)
• Description of the new capability your feature brings
• Comment on how it will impact other code components and users
• A list of limitations that this feature removes or introduces
• Summaries of the below sections

Requirements

Record the results of any requirements analysis here. It should fully specify what a complete feature looks like. This text can then be consulted when future changes to the codebase may have impact on this feature and developers can avoid introducing a regression. Capture any current pain points experienced by users (or developers) and outline how this feature intends to remove them.

You should be able to turn this into a numbered list of requirements which you can use to inform your test specification. e.g.

1. This feature must enable capability Z between component x and component y
2. Users must be able to enable/disable this feature via the config file
3. If dependency U or V are missing during build we default to previous behaviour
4. Enabling this feature should improve computation time under conditons A,B,C

Functional

Here we explain how a user will interact with the feature.

You should lay out the specification for any external interface or control here (e.g. an API call or a config file parameter and how you turn it on or off and ).

You should describe how the computer's state will change when running this feature and how a user will experience that. Is something printed to terminal or written to file? Does a new window appear? How are users signposted to the write location?

This may affect

Build

Details on how it impacts build/compile workflows. Does the user need to provide any flags, BYOS, etc...

Configuration

Details on how it impacts configuration/input files

Run

Details on how it impacts the overall package workflow as well as any changes to the system state, including terminal/file IO or other UI changes.

Architectural

Here we explain how the code is architected and interacts with other components. If you're using a well known design pattern or introducing a new class you should explain why the choice is being made and how it relates to the existing hierarchy and data structures.

This is the place to include UML diagrams (if using).

You should fully describe any limitations that this feature will introduce or any requirements it will place on future features. For instance, creating a dependency on library X.

You should lay out the specification for any internal code interfaces here.

You should specify the impact your feature will have on other components.

Integration

This section should outline how the feature relates to existing code on a system-level and any exisiting workflows or third-party software used by developers or users. This is a good place for flowcharts of proposed workflows for your finished feature.

Information about any dependencies with specific information about how they depend on one another could also be captured here. A good example would be to note which outputs from an external program are being supplied as inputs to the main program and how your feature accesses that. You could mention I/O during operation or you could talk about any post-processing steps.

Test Specification

Using the list of requirements generated earlier, you should be able to write a list of test objecives which provide a high-level definition or summary of corresponding tests that you will provide with your pull request (or an a follow-up issue, linked to an issue number and submitted within the code itself). E.g.

1. Initialize component and verify that file was created following call to method X
2. Run the program using config file A with feature parameter set to 'on' and config file B with feature parameter set to 'off'
3. Modify CMakeLists for one test executable such that library X is not available during compile
4. Create a test to add to the collection of perfomance tests and create a test that compares the on and off state.

In addition to tests for any special cases that arose during development (e.g. for different variables types, magic numbers of cores/nodes or race conditions where unavoidable).

Ths section of the specification not replace comments that are included at the top of each test which should describe how the test functions. However it should provide enough context such that a future developer could determine if it is safe to remove or modify a particular test.

Documentation Impact

For anything which is designed to or indirectly affects the user experience or removes or adds a limitation to the capability of the code, a corresponding change should be made to the documentation.

This a good place to note any like impact on the documentation and can be discussed at design review and during the pull request review stage.