Version 1 of 2 · · d2 (moved from d2spec) · in person · Current version

name
d3-f-impl
description
Implementations — the builds of a project's spec: d2 prototypes and code implementations, their stacks and their own docs. Get skills only from /api/v2/skills/d3.
feature
impl
concepts
[impl, stack]
tags
#skill #feature #d3skill #wip
project
d2spec

d3-f-impl

Intro

Implementations: the builds of a project's spec.

An implementation is one build of the project's spec. The design stays neutral — a kind of mechanism, never a product or a language — and everything specific to one build lives in that implementation's own docs. A d2 implementation is a prototype made directly as d2 apps; a code implementation is a real build on a stack, in a repository, by builders. Design docs and their layers: d3-f-design.

Essentials

  • R-impl-1 The Spec and Design never name a product, a language or a file: that goes in the implementation's own docs.
  • R-impl-2 Each implementation keeps its own As built, Code, Routes and Test topics; builders write those and nothing else.
  • R-impl-3 A ticket names the implementation it is for, or is spec-level.
  • R-impl-4 An implementation declares its routes and codes once, beside the code that serves them, and its lists are generated from that; its route topic holds only what a generated list can't say (d3-f-design › build_declared).

Concepts

impl

An implementation: one build of the project's spec. Also called: implementation, prototype (kind d2), build, code base (kind code). Fields: name (<impl> in a project with one), kind (d2 | code), stack (for code), repository and work branch, docs (its As built, Code, Routes and Test topics), deploy target. Kinds: d2 (pro and up) — alternative builds of the same spec made as d2 apps by the designer, no stack, repository or builders, each with its own As built notes so they can be compared; code (master) — a real build, with builders started for that implementation.

impl_list

  • Summary: the project's implementations, their kind, stack and docs.
  • When: before writing a ticket or an As built note; when asked which builds exist.
  • Needs: —
  • Call: GET /api/v2/topics/Settings:Implementations — until a project has that topic, its one implementation is in its facts (<impl>, <implDocs>).
  • Rules: R-impl-3.
  • Errors: E_NOT_FOUND → no such topic yet: use the project's facts.
  • Gotchas: —

impl_add

  • Summary: a new implementation is a line in the project's list plus its own doc topics.
  • When: your person wants another prototype, or a code build on a new stack.
  • Needs: its name, kind and, for code, its stack, repository and work branch — from your person.
  • Call: add it to Settings:Implementations through its draft (d3-f-drafts › draft_save) → create its As built, Code, Routes and Test topics.
  • Rules: R-impl-2. Name the docs after the implementation.
  • Errors: —
  • Gotchas: —

impl_docs

  • Summary: which topics belong to an implementation — and so to its builders, not to the design.
  • When: folding a builder's As built note; deciding where a fact goes.
  • Needs: the implementation's name.
  • Call: impl_list → its docs (<implDocs> in a project with one).
  • Rules: R-impl-1, R-impl-2. What a build settled for the design comes back as suggested updates (d3-f-design › layer_asBuilt); the designer makes those edits.
  • Errors: —
  • Gotchas: —

impl_compare

  • Summary: compare prototypes of one spec by their As built notes, not by memory.
  • When: your person is choosing between d2 prototypes.
  • Needs: two or more d2 implementations of the same spec section.
  • Call: read each one's As built section for the feature (d3-f-topics › section_read) → a short table: what each does differently, what each cost.
  • Rules: Compare against the Spec's behaviour lines, one row per code.
  • Errors: —
  • Gotchas: —

impl_handoff

  • Summary: hand a prototyped design to a code build: the spec, the design and the chosen prototype's As built.
  • When: a prototyped feature is ready to be built for real.
  • Needs: your person's choice of prototype; the Spec and Design sections published.
  • Call: one item for the receiving project's designer (d3-f-pipeline › item_file) linking the Spec and Design sections and the chosen prototype's As built.
  • Rules: R-impl-1. The receiving side writes its own tickets; a prototype's code is evidence, never the build.
  • Errors: —
  • Gotchas: —

stack

The technologies of a code implementation, each with its own skill (d3-f-impl-<tech>). Also called: tech stack. A builder on an implementation uses the repository skill (d3-f-git) and each skill of its stack.

Errors

  • E_NOT_FOUND — the project has no Settings:Implementations yet → its facts name its one implementation. see #impl_list