Standards and project config

This is an illustrative run on the sample project my-api. It shows how global and project standards and the two config.yaml files decide what each command reads.

The filesCopy Anchor Link

<home> is the folder theway path prints. Four files are added to the shipped content:

• <home>/standards/test-first.md, a global standard for the develop phase only:

  Copy Text

  ---
  applies_to: [develop]
  ---
  # Test First
  
  Write the failing test before the code it covers.

• <home>/projects/-home-you-code-my-api/standards/api-style.md, a project standard with no frontmatter:

  Copy Text

  # API Style
  
  Every error response is JSON: {"error": "<message>"}.

• <home>/config.yaml, the shipped file with one value changed, which enables the opt-in quality standard for every project:

  Copy Text

  standards:
    quality:
      enabled: true

• <home>/projects/-home-you-code-my-api/config.yaml, which turns it off again for my-api:

  Copy Text

  standards:
    quality:
      enabled: false

What each phase getsCopy Anchor Link

/theway:engineering, with or without --light, loads the engineering phase:

$ theway standards engineering
<home>/projects/-home-you-code-my-api/standards/api-style.md

/theway:workflow loads the develop phase:

$ theway standards develop
<home>/standards/test-first.md
<home>/projects/-home-you-code-my-api/standards/api-style.md

Why each file is or is not listed:

• api-style.md has no applies_to, so it applies to every phase. A user standard is enabled by default (api_style: true).
• test-first.md is listed for develop only: its applies_to names only that phase. Global files come before the project's.
• quality.md is listed in neither: the global config enables it, but the project config overrides the key with false.
• core-principles.md, sre.md and web-development.md are shipped opt-in standards that nothing enables.
• develop.md, interaction.md and authority.md are never listed: the commands read them by path, authority.md through theway authority. A global authority.md that .shipped.json does not list is your own standard, and is listed. Neither are commits.md and git-host.md, the convention standards theway workflow resolves.

The context a command loadsCopy Anchor Link

A command's first step runs theway context, which prints the same standards list next to the config it uses:

$ theway context develop add-x
home: <home>
project: -home-you-code-my-api
project_dir: <home>/projects/-home-you-code-my-api
change_dir: <home>/projects/-home-you-code-my-api/changes/add-x
standards:
  - <home>/standards/test-first.md
  - <home>/projects/-home-you-code-my-api/standards/api-style.md
config:
  standards:
    core_principles:
      enabled: false
    sre:
      enabled: false
    web_development:
      enabled: false
    quality:
      enabled: false
    api_style:
      enabled: true
    test_first:
      enabled: true
  workflow:
    defaults: {}

change_dir is printed even though add-x has no folder yet. Every agent of /theway:workflow gets the two paths of standards, and its reports name them: test-first.md, api-style.md.

See Configuration for every key.