Skip to content

ProjectSpec Format

A ProjectSpec is a sase format specification for a project plan consisting of multiple CLs (change lists). The format starts with a BUG field, followed by a collection of ChangeSpecs (see change_spec.md), each separated by two blank lines.

ProjectSpec files are stored at ~/.sase/projects/<filename>/<filename>.gp.

Format

A ProjectSpec starts with a BUG field at the top, followed by one or more ChangeSpecs, each separated by two blank lines. PARENT and CL are optional (omit them for the initial / unparented state — see change_spec.md):

BUG: <BUG_ID>


NAME: <NAME1>
DESCRIPTION:
  <TITLE1>

  <BODY1>
STATUS: <STATUS1>


NAME: <NAME2>
DESCRIPTION:
  <TITLE2>

  <BODY2>
PARENT: <NAME1>
STATUS: <STATUS2>

BUG Field

The BUG field is required at the very top of the ProjectSpec file, separated by two blank lines from the first ChangeSpec:

  • BUG: Bug ID to track this project. Supports multiple formats:
  • Plain ID: BUG: 12345
  • URL format: BUG: http://b/12345 or BUG: https://b/12345

ChangeSpec Fields

Each ChangeSpec within a ProjectSpec must contain the following fields:

  1. NAME: Must start with the project filename (without .gp extension) followed by an underscore and a descriptive suffix (words separated by underscores). Format: <BASENAME>_<descriptive_suffix> where the suffix thoughtfully describes the CL's intent (strive for shorter names)
  2. DESCRIPTION:
  3. First line (TITLE): A brief one-line description of the CL (2-space indented)
  4. Followed by a blank line (still 2-space indented)
  5. Body (BODY): Multi-line detailed description of what the CL does, including:
    • What changes are being made
    • Why the changes are needed
    • High-level approach or implementation details
  6. All DESCRIPTION lines must be 2-space indented
  7. DO NOT include file modification lists - that will be handled by a different workflow
  8. PARENT (optional): The NAME of the parent CL that must be completed first. Omit the field entirely when the CL has no dependencies (preferred for parallelization). The PARENT field is a ChangeSpec name, never a VCS ref — sase commit drops the PARENT field and warns when the value passed via -p does not resolve to an existing ChangeSpec.
  9. CL / PR (optional): Identifier of the created CL/PR. Omit the field entirely until the CL exists; both CL: and PR: are accepted and treated identically. Supported value formats:
  10. URL format: CL: http://cl/12345 or https://cl/12345
  11. GitHub PR URL: PR: https://github.com/<owner>/<repo>/pull/<N>
  12. STATUS: Must be one of the valid statuses: WIP, Draft, Ready, Mailed, Submitted, Reverted, Archived. New ChangeSpecs typically start as "WIP". See change_spec.md for the full status lifecycle.

Example

BUG: 12345


NAME: my-project_add_config_parser
DESCRIPTION:
  Add configuration file parser for user settings

  This CL implements a YAML-based configuration parser that reads
  user settings from ~/.myapp/config.yaml. The parser will include
  a ConfigParser class with load() and validate() methods, along
  with type definitions for the configuration schema. Tests will
  cover valid YAML parsing, invalid config validation, and missing
  file handling.
STATUS: WIP


NAME: my-project_integrate_parser
DESCRIPTION:
  Integrate config parser into main application

  This CL integrates the configuration parser from the previous CL
  into the main application initialization flow. The main application
  will import ConfigParser and load the config at startup, with proper
  error handling for invalid configurations. Tests will verify both
  valid and invalid config scenarios.
PARENT: my-project_add_config_parser
STATUS: WIP


NAME: my-project_add_docs
DESCRIPTION:
  Add documentation for configuration system

  This CL adds user-facing documentation explaining how to configure
  the application using the config file. The documentation will cover
  the configuration file format, provide examples of common scenarios,
  and document all available configuration options.
PARENT: my-project_integrate_parser
STATUS: WIP

Important Notes

  • BUG field: Must be the first line of the ProjectSpec file, followed by two blank lines
  • Blank lines between ChangeSpecs: Each ChangeSpec must be separated by exactly two blank lines
  • NAME field: All ChangeSpecs in a project MUST start with <basename>_ where basename is the project filename (without .gp), followed by a descriptive suffix (words separated by underscores, strive for shorter names)
  • CL / PR field: Omit until the CL/PR is created; once it exists, set to its URL (or PR URL for GitHub)
  • STATUS field: Must be a valid status (WIP, Draft, Ready, Mailed, Submitted, Reverted, Archived). New ChangeSpecs typically start as "WIP"
  • PARENT field: Optional. Omit it when there is no dependency; otherwise set it to the NAME of the parent CL
  • No file modifications: The DESCRIPTION should NOT include specific file modification lists — that will be handled by a different workflow