patch: Add metadata.yaml requirement to docs (#255)

.github/workflows/release_charm.md

@@ -29,4 +29,19 @@ jobs:
       charmhub-token: ${{ secrets.CHARMHUB_TOKEN }}
     permissions:
       contents: write  # Needed to create GitHub release
-```
+```
+
+### metadata.yaml required
+This workflow requires the charm directory (directory with charmcraft.yaml) to contain a metadata.yaml file with the `name` key. If the charm uses OCI images (Kubernetes only), metadata.yaml must also contain the `resources` key. Syntax: https://juju.is/docs/sdk/metadata-yaml
+
+"Unified charmcraft.yaml syntax" (where actions.yaml, charmcraft.yaml, config.yaml, and metadata.yaml are combined into a single charmcraft.yaml file) is not supported.
+
+#### Rationale
+It is simpler (for CI/CD tooling, developers, etc.) to have a consistent approach—either "unified charmcraft.yaml syntax" or separate files.
+
+With "unified charmcraft.yaml syntax", charmcraft extracts the data back into actions.yaml, config.yaml, and metadata.yaml when packing the charm—but it removes comments from the YAML.
+
+Benefits of separate files:
+- no difference in files between source repository and *.charm artifact that would be confusing to developers
+- comments in YAML files retained
+- charmcraft just copies the files into the *.charm artifact, instead of using more complicated logic to extract that information (which would create more surface area for bugs)

.github/workflows/sync_docs.md

@@ -24,6 +24,13 @@ jobs:
       pull-requests: write  # Needed to create PR
 ```
 
+### metadata.yaml required
+This workflow requires the charm directory (directory with charmcraft.yaml) to contain a metadata.yaml file with the `docs` key. Syntax: https://juju.is/docs/sdk/metadata-yaml
+
+"Unified charmcraft.yaml syntax" (where actions.yaml, charmcraft.yaml, config.yaml, and metadata.yaml are combined into a single charmcraft.yaml file) is not supported.
+
+Rationale in [release_charm.md](release_charm.md#rationale)
+
 ## Behavior
 
 Downloads all Discourse topics in the charm's Charmhub documentation to `/docs/` directory in the charm's repository.