Skip to content

docs: add a Local state page for score-compose and score-k8s#292

Open
Siddhartha-singh01 wants to merge 1 commit into
score-spec:mainfrom
Siddhartha-singh01:docs/workspace-state-documentation
Open

docs: add a Local state page for score-compose and score-k8s#292
Siddhartha-singh01 wants to merge 1 commit into
score-spec:mainfrom
Siddhartha-singh01:docs/workspace-state-documentation

Conversation

@Siddhartha-singh01
Copy link
Copy Markdown
Contributor

Closes #266

Adds a dedicated Local state page under Score Implementation CLIs
that consolidates the answers to the questions in the issue: what the
.score-compose/ and .score-k8s/ directories are for, whether they are
mandatory, when they help, and when the platform should own state instead.

What the page covers

  • What's in the directory state.yaml and *.provisioners.yaml,
    with a tree showing the post-init layout.
  • Is it mandatory? yes for the default implementations; both
    generate commands fail without an init.
  • When local state helps a concrete walk-through using a postgres
    resource, showing how the random password written to state.yaml
    stays stable across successive generate runs.
  • When you don't need it platform-managed secrets on Kubernetes,
    managed Score implementations.
  • Excluding it from version control .gitignore guidance.
  • Persisting state in CI/CD with a pointer to the existing
    score-k8s example instead of duplicating it.
  • Removing local state clearing the directory and starting over.

Cross-links added

The four existing places that touch the topic now link back to the new
page so they stop being the de-facto documentation:

  • score-compose CLI init section
  • score-k8s CLI init section
  • Maintaining score-k8s state in the CI/CD how-to
  • The init subcommand bullet in Create a Score implementation

Each cross-link is a single sentence appended to the existing paragraph;
no surrounding text is restructured.

Test plan

  • yarn run hugo builds clean
  • yarn run dprint check passes
  • New page renders at /docs/score-implementation/local-state/
  • All relref cross-links resolve
  • Factual claims spot-checked against the score-compose postgres
    provisioner and the existing CLI docs

Adds a dedicated page that consolidates what the .score-compose/ and .score-k8s/ directories contain, whether they are mandatory, when the local state helps (random secrets, non-hermetic outputs across multiple generate runs), and when the target platform should own state instead. Cross-links the four existing places that touch the topic so they point back to the central page.

Signed-off-by: Siddhartha Singh <siddharthagithub0007@gmail.com>
@Siddhartha-singh01
Copy link
Copy Markdown
Contributor Author

Siddhartha-singh01 commented May 20, 2026

Hi @mathieu-benoit first off, really sorry I went ahead without waiting for the formal assignment on this one. I got into the issue, started reading through the five places it's mentioned , and before I knew it I had a full draft ready. I opened it as #292.

Could you take a look whenever you have a moment? If anything in there feels off the placement under Score Implementation CLIs, the section ordering, wording that misses a nuance, the postgres example not being quite the right one, or anything else please be completely candid. I'd much rather rework it now than have something half-right merged. Whatever you decide on the page, I'll respect it fully and make the changes happily.

Thanks for the detailed outline in the issue it made the page much easier to put together than starting from a blank canvas.

@mathieu-benoit
Copy link
Copy Markdown
Contributor

@Siddhartha-singh01, no worries at all, thanks for being proactive and taking initiatives like this!

I'll review this later.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Documentation about the state folder/file of score-compose and score-k8s is missing

2 participants