Skip to content

Instantly share code, notes, and snippets.

@vpalos
Last active September 7, 2017 12:43
Show Gist options
  • Save vpalos/151e260c589c3f11d4d93fbd67c232b4 to your computer and use it in GitHub Desktop.
Save vpalos/151e260c589c3f11d4d93fbd67c232b4 to your computer and use it in GitHub Desktop.
---
#
# Some pre-defined meta-values provided for this schema (required).
#
identity:
company: DevFactory
version: 2.0
#
# All fields named `comment` simply provide a short explanatory paragraph for
# the context they are found in. They are useful for all who read the template
# file, but also for the tools that will generate the input UIs. These texts
# will not persist in the final specs but are present during spec-writing as
# comments or as placeholders in empty input fields.
#
comment: >
This document represents an L1 specification which describes in thorough
technical detail a single Milestone; it can consist of a single file, or
multiple files, imported via referencing.
Syntax is [SpecL Markdown](https://...) (i.e. Markdown + Gherkin).
#
# These are rendering options to be used when publishing a spec. However, the
# chosen rendering tool may choose to ignore or ovewrite them.
#
# You can see how referencing to other nodes in the spec can work.
#
title: >
L1 Spec: {/Metadata/Product Name} - {/Metadata/Release Name} - M{/Metadata/Milestone Number}
header: >
L1 Spec: **Milestone {/Metadata/Milestone Number}**
Release {/Metadata/Release Name}
{/Metadata/Product Name}
#
# References can have fall-back values (in case referenced value is missing).
#
footer: >
L1 schema version {schema: version} - Author: {/Metadata/Owner | "Unknown"} - {schema: company | "DF"}
#
# The entire specification is made of node, which can be nested. These define
# sections, input values and pretty much anything else.
#
schema:
#
# This is a node: a section definition.
#
Metadata:
comment: >
This is expected to be the first section of the Spec and it contains
complete identification information.
type: tree # This section must be a tree object (just like a JS object).
strict: true # I.e. authors can't add nodes other than the ones defined here (default).
children:
#
# Sub-nodes of Metadata.
#
Product Name:
type: string
comment: "Short Capitalized Product Name."
# Any node (even whole sections) can enforce validation rules.
# These rules are interpreted based on the node's type.
pattern: /^[a-zA-Z0-9 -]+$/
min: 3
max: 100
Release Name:
type:
- number
- string
comment: "Usually a version number, but can be a name also."
pattern: /^[a-zA-Z0-9.-]+$/
L2 Spec Link:
type: string
required: false # A node is required by default.
comment: Link to the parent L2 Spec (if any).
# Here's a pre-defined validation rule.
pattern: {patterns: uri}
Milestone Number:
type: number
comment: "A simple integer denoting the milestone count."
min: 1
Milestone Name:
type: string
comment: "A name for this milestone."
pattern: {patterns: identifier}
JIRA Ticket:
type: string
comment: "A ticket code, such as JIRA-123."
pattern: "^[A-Z]+-[0-9]+$"
#
# Custom JS validators can perform specialized checks.
#
validators:
- {file(./validators/jira.js): isValidTicket}
Owner:
type: string
comment: "spec-author@email.here"
pattern: {patterns: email}
Original:
type: string
comment: URI always pointing to the original spec.
validators:
- {file(./validators/specs.js): isValidL1Uri}
#
# This section is a list of objects (between 1 and 100).
#
Glossary:
comment: Complete this list to introduce any acronyms or jargon used in this spec.
type: list
min: 1
max: 100
item:
type: tree
strict: true
children:
Term:
type: string
Definition:
type: string
#
# Use `samples` in any node to add sample values in the generated template.
# These values must pass any validation rules defined for the node. Usually
# the author is expected to eventually replace them (though not required).
#
samples:
-
Term: ET1
Definition: Example Term 1
-
Term: ET2
Definition: Example Term 2
#
# This defines a variable list of capabilities (minimum 1).
#
Capabilities:
comment: >
Capabilities fall into a number of different Capability Types. This is expected
to expand over time as our product management and engineering practices evolve.
Any TPM should feel empowered to define a new capability type and template and
add it to this repository.
type: list
min: 1
max: 100
item:
type: tree
children:
Summary:
type: string
#
# This node implements the `feature` type which is baeically Gherkin source
# code (possibly combined with Markdown syntax).
#
Definition:
type: feature
# For `feature` nodes, we could even use pre-defined Gherkin files
# to enforce baselines for how the final text must look. The author's
# content must comply to at least one of the baselines.
baseline:
- {file(./features/api.feature)}
- {file(./features/ui.feature)}
- {file(./features/performance.feature)}
- {file(./features/scalability.feature)}
- {file(./features/report.feature)}
- {file(./features/monitoring.feature)}
- {file(./features/rollout.feature)}
...
samples:
-
Summary: UI enables login.
Definition: >
{file(./caps/login-screen.md)}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment