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

[mathieu-benoit]

We are getting more and more questions and feedback about the state folder/file of score-compose and score-k8s:

• What's the purpose?
• Is it mandatory?

Today, we have five places where we talk about it:

• https://docs.score.dev/docs/score-implementation/score-compose/cli/#init

initializes a .score-compose/ working directory if it doesn’t already exist. The .score-compose/ directory is used to store local state and should be excluded from version control systems such as Git by adding it to your .gitignore file.

• https://docs.score.dev/docs/score-implementation/score-k8s/cli/#init

The '.score-k8s' directory contains state that will be used to generate any Kubernetes resource manifests including potentially sensitive data and raw secrets, so this should not be checked into generic source control.

• https://docs.score.dev/docs/how-to/score-cicd-pipelines/#maintaining-score-k8s-state

CI Workflows typically start with a clean slate every time they execute. No state is stored on disk between runs. However, score-k8s does store unique data, random seeds, and non-hermetic attributes in a .score-k8s/state.yaml file. For best results, this file should be restored before running score-k8s generate.

• https://docs.score.dev/docs/how-to/create-a-score-implementation/

Implement an init subcommand to initialize any local state in the project directory. This isn’t required if the implementation requires no local state.

But we still need to:

• find a dedicated location in the docs where we describe this concept of state folder/file
• expand existing description to "what if we don't use it?", "when should we use it?", etc.

Use cases to describe in addition to what's above:

• illustrate the state in default provisioners to show when state can help:
• illustrate when not using the state when secrets, etc. are managed in the platform itself, for example in Kubernetes:

any state that is generated should be contained in cluster (eg. DatabaseInstance should create it’s own secrets, not created in provider).

• tl,dr the state file is more for local innerloop if you want to generate random secrets/values and do multiple generate --> deploy. Bu the recommendation and best practices is to not do that and leverage the platform itself to generate these and rely on its own state management.

[Siddhartha-singh01]

Hi @mathieu-benoit

This is a really useful one to document properly I've seen the "what's the state folder for?" and "is it mandatory?" questions come up a lot too, and right now the answer is spread across five different places.

I'd love to take this on. My rough plan would be:

• Add a dedicated section in the docs that explains the concept of the .score-compose/ and .score-k8s/ state folder/file in one place.

• Expand it to answer the practical questions what is its purpose?, is it mandatory?, when should I use it vs not?, and the .gitignore recommendation.

• Cover the use cases you listed: when state helps (random secrets/values across multiple generate → deploy cycles in the local inner loop), and when it isn't needed (secrets and state managed by the platform itself, for example in Kubernetes).

• Cross-link the five existing places so they point back to the new central section.

Could you please assign this to me? Happy to discuss the best home for the new section before I start.

Thanks!