Skip to content

Configurable paths to README.md, CHANGELOG.md, and LICENSES folder #333

@simonas-drauksas-sensmetry

Description

sysand build currently looks for README.md, CHANGELOG.md, and LICENSES/<id>.txt at hardcoded paths under the project root. Projects often want to override these — most commonly when the Git repository's README.md is a contributor-facing landing page that is not what should ship in the KPAR, and the package README lives at a separate path like PUBLIC_README.md.

Proposal: Add a [build] table to sysand.toml letting projects override these source paths or disable bundling entirely.

Proposed schema

[build]
# String → use that path; `false` → disabled; omitted → default ("README.md").
readme = "PUBLIC_README.md"

# Same shape as `readme`. Default "CHANGELOG.md".
changelog = "PUBLIC_CHANGELOG.md"

# String → look up license files in that dir; `false` → don't bundle any
# license files; omitted → default ("LICENSES").
licenses_dir = "legal/licenses"

Archive paths inside the KPAR stay canonical (README.md, CHANGELOG.md, LICENSES/<id>.txt) regardless of source path — consumers don't need to know how the author named files on disk.

Key design decisions

  • sysand.toml, not .project.json. .project.json is the KerML-spec interchange file embedded in the KPAR; adding a sysand-only field there pollutes a standardized surface. [build] is purely a tool-side authoring concern.
  • Project-local only. A [build] table in user-level ($XDG_CONFIG_HOME/sysand/sysand.toml) is warned about and ignored. Two contributors building the same project must produce identical KPARs; [build] describes the project's output, not user preferences. Asymmetric with [[index]]/[[project]] on purpose.
  • Disable via false. readme = false opts out entirely, with no warning regardless of what's on disk.
  • Missing-file behavior is asymmetric.
    • readme / changelog omitted + file absent → silent skip (today's behavior, preserved).
    • readme / changelog set to an explicit path + file absent → warn.
    • licenses_dir: warn per missing license file (named by SPDX expression in .project.json's license) regardless of whether the dir was overridden — the intent comes from .project.json, not sysand.toml.

Open questions

  • Should readme = "X" + file missing be a hard error instead of a warning? An explicit path is a stronger claim of intent.
  • Should we also move --compression or other building-specific settings to this table?

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions