Engineering specifications are the means by which we discuss and ratify what we’d like to build across all of our supported platforms. All specs have a consistent shape and are expected to evolve over time.
Purpose: To provide a checklist for an engineer to validate their implementation against.
Shape: Specs start with an overview of the topic and then a broken-down minimum-viable product (MVP) specification. Each part of the MVP specification should be as small as possible, and no smaller.
Order of information: The spec should be readable in a top-down fashion.
Audience: The audience is expected to be highly technical, with a strong understanding of types, object oriented programming, and functional programming.
Build it first: If you are writing a spec you ideally already have a working implementation in your language of choice. Do not paste this implementation into the spec verbatim. Your role as spec writer is to break the implementation apart into a checklist. Another engineer - potentially thinking in a language different from your own - can then follow this checklist.
Language-agnostic: Avoid use of language-specific features where possible. If a language-specific feature is necessary, explain why. Examples of language-specific features include:
- Function short-hand (
$0notation in swift).
- Named arguments (Objective-C and swift).
- Protocol extensions (swift).
Features we expect to be available in all of our supported languages:
- Compile-time type enforcement.
Conformance: Specs do not need to be 100% byte-for-byte accurate. The goal is to communicate the intent and shape of the topic, not its literal implementation.
Features: Identify non-MVP features and break them apart into separate
feature specifications. A feature specification can build off of an MVP in a parallel fashion.
Feature specifications live in a separate file from their MVP. E.g. for
topic.md, a feature might
topic-feature.md. Feature specs have similar shapes to MVP specs.
Shape of a spec
Presented below is the outline of an engineering specification. We discuss each section in more detail further below.
--- key: value key: value ... --- # <topic> specification This is the engineering specification for the `<topic>`. ## Overview A high-level overview of the topic. Discuss new concepts where relevant. ## Examples An optional set of examples showing use of the topic. ## MVP ### Specific thing to build And how to build it.
All specs start with a yaml preamble. This preamble includes relevant metadata.
Indicates the current status of the page.
Date must be long-form
Month day, year format.
Status can be any of
status: date: December 13, 2016 is: Draft
Defines the expected end-user knowledge level for this topic.
There are four knowledge levels: L1-L4.
The library this API should live within.
All library names are lower-cased and hyphenated.
A list of absolute paths to other starmap files.
A dependency is a spec that must be built before this spec can be built.
depends_on: - /starmap/specifications/primitives/gesture_recognizers/GestureRecognizer - /starmap/specifications/streams/operators/foundation/$._map
Operators should define their expected input and output types.
streamtype: in: GestureRecognizer out: Point
Link to the platform’s source and tests, when available.
We use the following platform names:
availability: - platform: name: <platform name> url: <source url> tests_url: <tests url> - platform: name: <platform name> url: <source url> tests_url: <tests url>