Document what a configuration change requires

config-as-code/configuration-changes.mdx

@@ -0,0 +1,94 @@
+---
+title: "What happens after a configuration change?"
+description: "Understand which Ravion phases a module configuration change requires."
+"og:image": "https://www.ravion.com/og/docs/config-as-code/configuration-changes.png"
+"twitter:image": "https://www.ravion.com/og/docs/config-as-code/configuration-changes.png"
+---
+
+When you change a module input, Ravion identifies the operational phases
+required for the change to take effect. Saving the configuration does not
+necessarily run every required phase.
+
+For background on managing a project configuration file, see [Project config
+file](/config-as-code/project-config-file).
+
+## The phases
+
+| Phase | What it does |
+| --- | --- |
+| **Stack update** | Runs the module's stack pipeline to create or update infrastructure. |
+| **Rebuild** | Creates a new application image or other build artifact. |
+| **Deploy** | Releases the new configuration or artifact to the running module. |
+
+The phases are separate. A stack update changes infrastructure, but does not
+release a new application artifact. A rebuild creates an artifact, but does not
+make it the active release until a deploy promotes it.
+
+See [Build](/modules/build) and [Deploy](/modules/deploy) for more about those
+pipeline steps.
+
+## Examples
+
+The required phases depend on the module definition and the input you change.
+These examples use inputs from Ravion's standard module definitions:
+
+| Module input | Required phases | Why |
+| --- | --- | --- |
+| `rvn-ecs-web` `desired_count` | Stack update | The desired service capacity is infrastructure configuration. |
+| `rvn-ec2-service` `environment_variables` or `secrets` | Stack update and deploy | The stack carries the runtime configuration, and the deploy renders it into the app environment on running instances. |
+| `rvn-aws-static` `build_environment_variables` | Rebuild and deploy | The build uploads a versioned static directory, and the deploy promotes that directory to production. |
+
+The per-input `applies_on` field records this lifecycle metadata in a module
+definition. See the [module definition schema reference](/module-definitions/definition-schema/inputs).
+
+## Check what a change requires
+
+### Dashboard
+
+When you save a module configuration, the confirmation dialog shows which
+phases the change requires and what the selected save option will do.
+
+Saving the configuration records the new values. It does not automatically
+rebuild an artifact or deploy it unless you choose an option that performs
+those operations. If a later phase is required, run that phase after the
+configuration save completes.
+
+### CLI
+
+The `ravion project config apply` command shows the required phases in the
+`REQUIRES` column. In an interactive terminal, it also displays the planned
+changes and asks you to confirm them:
+
+```bash
+ravion project config apply <project-id> --file ravion.yaml
+```
+
+Use a dry run to inspect the plan without applying it:
+
+```bash
+ravion project config apply <project-id> \
+  --file ravion.yaml \
+  --dry-run
+```
+
+Use `--yes` to skip the confirmation prompt in scripts:
+
+```bash
+ravion project config apply <project-id> \
+  --file ravion.yaml \
+  --yes
+```
+
+The `REQUIRES` column uses **stack update**, **rebuild**, and **deploy** so you
+can see which work remains after the configuration apply.
+
+## Older module definitions
+
+<Warning>
+  Module definitions published before lifecycle metadata was introduced do not
+  provide enough information to determine every required phase.
+</Warning>
+
+If Ravion reports unknown phase metadata, assume the change requires a stack
+update and a deploy. Run the stack update, rebuild if the module needs a new
+artifact, and then deploy the resulting configuration or artifact.

docs.json

@@ -52,6 +52,7 @@
             "group": "Config as code",
             "pages": [
               "config-as-code/project-config-file",
+              "config-as-code/configuration-changes",
               "config-as-code/pipeline-config-file",
               "config-as-code/ci-integration"
             ]