Various fixes

.ci/scripts/docgen.py

@@ -41,7 +41,7 @@ def generate_markdown_table(policies: List[PolicyMetadata]) -> str:
     rows = []
     for p in policies:
         description = p.description.replace("\n", " ").strip()
-        ghcr_path = f"ghcr.io/updatecli/policies/{os.path.basename(p.path)}"
+        ghcr_path = f"ghcr.io/{os.path.normpath(os.path.dirname(p.path))}"
         readme_url = replace_filename_in_url(f"https://github.com/updatecli/policies/tree/main/{p.path}", "README.md")
         rows.append(f"| `{ghcr_path or '-'}` | {p.version or '-'} | {description or '-'} | {f"[link]({readme_url})" } |")
     return header + separator + "\n".join(rows)

CONTRIBUTING.adoc

@@ -0,0 +1,123 @@
+= CONTRIBUTING
+
+Thank you for your interest in contributing to this project.
+Here is a none exclusive list of contribution you can do.
+
+== Documentation
+
+This project would benefit from clearer policy README files. Please improve each policy's README to explain how to use and configure the policy.
+
+To inspect a policy bundle locally (manifest and default values):
+
+[source,shell]
+----
+
+# Show the generated manifest (uses files in the policy bundle directory)
+
+updatecli manifest show --config updatecli.d --values values.yaml
+
+# Show the manifest and render a graph (Mermaid)
+
+updatecli manifest show --config updatecli.d --values values.yaml --graph --graph-flavor mermaid
+----
+
+Notes:
+
+* `--config updatecli.d` reads policy manifests shipped inside the policy bundle.
+* `--values values.yaml` overrides default policy values for local inspection.
+
+When running policies, prefer pinning by version or digest to ensure reproducible runs:
+
+* By tag:  `ghcr.io/updatecli/policies/autodiscovery/golang:1.0.0`
+* By digest: `ghcr.io/updatecli/policies/autodiscovery/golang@sha256:<digest>`
+
+Authentication:
+
+* Public pulls usually work, but authenticating with GHCR reduces rate limits:
+[source,shell]
+
+----
+
+docker login ghcr.io
+----
+
+* For private bundles, provide registry credentials to your runtime or via Updatecli's registry auth options.
+
+Publishing:
+
+* Policies in this repository are published automatically by CI when `Policy.yaml` version is bumped.
+* See the `Policy.yaml` template below and ensure you update the `version` field for releases.
+
+Policy inspection and usage summary:
+
+* Inspect: `updatecli manifest show --config updatecli.d --values values.yaml`
+* Dry-run: `updatecli diff ghcr.io/updatecli/policies/<path>:<version>`
+* Apply: `updatecli apply --config ghcr.io/updatecli/policies/<path>:<version>`
+
+Tip: add a short example `values.yaml` in each policy README to help users test quickly.
+
+== Updating Policy
+
+Before changing an existing policy, open a GitHub issue to discuss the proposed change. Use the issue to explain:
+
+* Motivation and user impact
+* Backwards compatibility implications
+* Required changes to `Policy.yaml`, `values.yaml`, or `updatecli.d`
+* Testing plan (how the change will be validated)
+
+When preparing a PR:
+
+* Bump `Policy.yaml` version for behavioural changes (semantic versioning).
+* Update `CHANGELOG.md` and the policy `README.md` with usage and configuration changes.
+* Add or update `values.yaml` examples if defaults change.
+* Ensure policy validation CI (lint/manifest tests) passes.
+
+PR checklist:
+
+* [ ] Issue opened describing the change (link in PR)
+* [ ] `Policy.yaml` version updated when needed
+* [ ] `CHANGELOG.md` updated
+* [ ] README and example `values.yaml` updated
+* [ ] All CI checks pass (policy validation workflow)
+
+Notes:
+
+* Policies are published automatically by CI when `Policy.yaml.version` is updated.
+* For large or breaking changes, discuss a migration plan in the issue and notify maintainers.
+* For security-related changes, include an explanation and coordinate disclosure with maintainers.
+
+== New Policy
+
+A new policy can be added by creating a new folder under the `updatecli/policies` directory.
+The subfolder path will be used as the policy name.
+
+For example if we want to create a policy named `autodiscovery/golang`, we need to create a folder named `updatecli/policies/autodiscovery/golang`.
+This policy will be named `ghcr.io/updatecli/policies/autodiscovery/golang` and will be published on `ghcr.io` docker registry.
+
+The policy folder must contain:
+
+* `Policy.yaml` file which contains the policy metadata.
+* `updatecli.d` directory which contains the policy configuration files.
+* `README.md` file which contains the policy documentation.
+* `CHANGELOG.md` file which contains the policy changelog.
+* `values.yaml` file which contains the default values for the policy.
+
+**Policy.yaml**
+
+The `Policy.yaml` file must contain at least the following fields:
+
+```yaml
+url: <link to this git repository>
+documentation: <link to the policy documentation>
+source: <link to this policy code>
+version: <policy version>
+changelog: <link to this policy changelog>
+description: <policy description with maximum 512 characters>
+```
+
+**Version**
+
+The version must be a valid semantic version. For example `1.0.0` or `1.0.0-beta.1`
+The version will be used as the "tag" for the policy such as `ghcr.io/updatecli/policies/autodiscovery/golang:1.0.0`
+
+Any change to the policy code must be reflected by a new version. Policies are automatically published on `ghcr.io` if the version is updated.

README.adoc

@@ -6,43 +6,41 @@ link:https://matrix.to/#/#Updatecli_community:gitter.im[image:https://img.shield
 link:https://github.com/updatecli/policies/blob/main/LICENSE[image:https://img.shields.io/github/license/updatecli/policies[GitHub]]
 link:https://img.shields.io/github/actions/workflow/status/updatecli/policies/validate.yaml?branch=main[image:https://img.shields.io/github/actions/workflow/status/updatecli/policies/validate.yaml?branch=main[GitHub Workflow Status]]
 
-
-These repository contains a list of common Updatecli policies that can be used to automate the update of various software components.
-These policies are published on `ghcr.io/updatecli/policies` docker registry and can be used directly by Updatecli users. 
-Policies are designed to be as generic as possible to fit most use cases and can be customized via values files at runtime.
-They follow semantic versioning to ensure compatibility and stability.
+These policies are a collection of official Updatecli bundles that automate common update tasks (Golang, npm, Docker, ...).
+Policies are published to the GitHub Container Registry under `ghcr.io/updatecli/policies` and follow semantic versioning.
 
 == Policies
 
-A list of all available policies can be found link:./POLICIES.md[here].
+A list of all available policies: link:./POLICIES.md[Full policy list]
 
-== Quick Start
+== Quick start
 
-Pull and inspect a policy manifest:
+Inspect a published policy manifest:
 
 [source,shell]
 ----
 updatecli manifest show ghcr.io/updatecli/policies/autodiscovery/golang:latest
 ----
 
-Run a single policy (dry-run):
+Dry-run (show what would change):
 
 [source,shell]
 ----
 updatecli diff ghcr.io/updatecli/policies/autodiscovery/golang:latest
 ----
 
-Apply a single policy:
+Apply a policy:
 
 [source,shell]
 ----
 updatecli apply --config ghcr.io/updatecli/policies/autodiscovery/golang:latest
 ----
 
-Compose multiple policies using an updatecli-compose file:
+Compose multiple policies from a local compose file:
 
 * Create `updatecli-compose.yaml` (example below).
 * Run:
+
 [source,shell]
 ----
 updatecli compose apply --config ./updatecli-compose.yaml
@@ -55,182 +53,62 @@ policies:
   - policy: "ghcr.io/updatecli/policies/autodiscovery/npm:latest"
 ----
 
-Please be aware that each policies comes with its own set of configuration options so please refer to the policy documentation for more information.
-You can replace the policy `ghcr.io/updatecli/policies/autodiscovery/all:latest` by any other policy available in this repository.
+Note: values passed at runtime override bundle defaults. See each policy README for available values.
 
-== Authentication / Registry
+== Authentication / registry
 
-Policies are published on `ghcr.io`. Public pulls usually work, but authenticating reduces rate-limiting:
+Policies are published on `ghcr.io`. Public pulls usually work, but authenticating reduces rate limiting and enables access to private bundles:
 
 [source,shell]
 ----
 docker login ghcr.io
 ----
 
-If you need to pull private policies, provide credentials via your container/runtime or via Updatecli's registry auth options.
-
-== HOWTO
-
-**Login**
-
-Even though all Updatecli policies published on `ghcr.io` are meant to be public, you'll probably need to authenticate to reduce rate limiting by running:
-
-    docker login ghcr.io
-
-**Publish**
-
-Each policies defines in this repository are automatically published on ghcr.io via a GitHub Action workflow
-
-**Show**
-
-We can see the content of the policy by running:
-
-    updatecli manifest show --config updatecli.d --values values.yaml
-
-**Use**
-
-There are two ways to execute an Updatecli policy, either running one policy or several policies at once.
-
-One policy can be executed by running:
-
-    updatecli apply --config ghcr.io/updatecli/policies/<policy-path>:<version>
-
-
-IMPORTANT: Any values files specified at runtime will override default values setting from the policy bundle
-
-Assuming we have a file named `updatecli-compose.yaml`, multiple policies can be composed and executed by running:
-
-        updatecli compose apply --config ./updatecli-compose.yaml
-
-.updatecli-compose.yaml
-```yaml
-policies:
-    - policy: "ghcr.io/updatecli/policies/autodiscovery/golang:latest"
-    - policy: "ghcr.io/updatecli/policies/autodiscovery/npm:latest"
-```
-
-More information about Updatecli compose feature can be found link:https://www.updatecli.io/docs/core/compose/[here]
+For private bundles provide credentials via your container runtime or Updatecli's registry auth options.
 
-== CONTRIBUTING
-
-Thank you for your interest in contributing to this project.
-Here is a none exclusive list of contribution you can do.
-
-=== Documentation
+== How to inspect & test locally
 
-This project would benefit from clearer policy README files. Please improve each policy's README to explain how to use and configure the policy.
-
-To inspect a policy bundle locally (manifest and default values):
+To inspect a policy bundle shipped inside a folder (useful for development):
 
 [source,shell]
 ----
-# Show the generated manifest (uses files in the policy bundle directory)
-updatecli manifest show --config updatecli.d --values values.yaml
-
-# Show the manifest and render a graph (Mermaid)
-updatecli manifest show --config updatecli.d --values values.yaml --graph --graph-flavor mermaid
+updatecli manifest show --config ./policy-folder/updatecli.d --values ./policy-folder/values.yaml
 ----
 
-Notes:
-* `--config updatecli.d` reads policy manifests shipped inside the policy bundle.
-* `--values values.yaml` overrides default policy values for local inspection.
-
-When running policies, prefer pinning by version or digest to ensure reproducible runs:
-* By tag:  `ghcr.io/updatecli/policies/autodiscovery/golang:1.0.0`
-* By digest: `ghcr.io/updatecli/policies/autodiscovery/golang@sha256:<digest>`
+Render graph (Mermaid):
 
-Authentication:
-* Public pulls usually work, but authenticating with GHCR reduces rate limits:
 [source,shell]
 ----
-docker login ghcr.io
+updatecli manifest show --config ./policy-folder/updatecli.d --values ./policy-folder/values.yaml --graph --graph-flavor mermaid
 ----
-* For private bundles, provide registry credentials to your runtime or via Updatecli's registry auth options.
-
-Publishing:
-* Policies in this repository are published automatically by CI when `Policy.yaml` version is bumped.
-* See the `Policy.yaml` template below and ensure you update the `version` field for releases.
-
-Policy inspection and usage summary:
-* Inspect: `updatecli manifest show --config updatecli.d --values values.yaml`
-* Dry-run: `updatecli diff ghcr.io/updatecli/policies/<path>:<version>`
-* Apply: `updatecli apply --config ghcr.io/updatecli/policies/<path>:<version>`
-
-Tip: add a short example `values.yaml` in each policy README to help users test quickly.
-
-=== Updating Policy
-
-Before changing an existing policy, open a GitHub issue to discuss the proposed change. Use the issue to explain:
-* Motivation and user impact
-* Backwards compatibility implications
-* Required changes to `Policy.yaml`, `values.yaml`, or `updatecli.d`
-* Testing plan (how the change will be validated)
 
-When preparing a PR:
-* Bump `Policy.yaml` version for behavioural changes (semantic versioning).
-* Update `CHANGELOG.md` and the policy `README.md` with usage and configuration changes.
-* Add or update `values.yaml` examples if defaults change.
-* Ensure policy validation CI (lint/manifest tests) passes.
+== Publishing
 
-PR checklist:
-* [ ] Issue opened describing the change (link in PR)
-* [ ] `Policy.yaml` version updated when needed
-* [ ] `CHANGELOG.md` updated
-* [ ] README and example `values.yaml` updated
-* [ ] All CI checks pass (policy validation workflow)
+Policies in this repository are published automatically by CI when `Policy.yaml` version is bumped. When changing a policy:
+* Update `Policy.yaml.version` following semver.
+* Update `CHANGELOG.md` and the policy `README.md`.
+* Ensure CI validation (lint/manifest tests) passes.
 
-Notes:
-* Policies are published automatically by CI when `Policy.yaml.version` is updated.
-* For large or breaking changes, discuss a migration plan in the issue and notify maintainers.
-* For security-related changes, include an explanation and coordinate disclosure with maintainers.
-
-=== New Policy
-
-A new policy can be added by creating a new folder under the `updatecli/policies` directory.
-The subfolder path will be used as the policy name.
-
-For example if we want to create a policy named `autodiscovery/golang`, we need to create a folder named `updatecli/policies/autodiscovery/golang`.
-This policy will be named `ghcr.io/updatecli/policies/autodiscovery/golang` and will be published on `ghcr.io` docker registry.
-
-The policy folder must contain:
-
-* `Policy.yaml` file which contains the policy metadata.
-* `updatecli.d` directory which contains the policy configuration files.
-* `README.md` file which contains the policy documentation.
-* `CHANGELOG.md` file which contains the policy changelog.
-* `values.yaml` file which contains the default values for the policy.
-
-**Policy.yaml**
-
-The `Policy.yaml` file must contain at least the following fields:
-
-```yaml
-url: <link to this git repository>
-documentation: <link to the policy documentation>
-source: <link to this policy code>
-version: <policy version>
-changelog: <link to this policy changelog>
-description: <policy description with maximum 512 characters>
-```
-
-**Version**
+== CONTRIBUTING
 
-The version must be a valid semantic version. For example `1.0.0` or `1.0.0-beta.1`
-The version will be used as the "tag" for the policy such as `ghcr.io/updatecli/policies/autodiscovery/golang:1.0.0`
+If you want to contribute, see link:./CONTRIBUTING.adoc[CONTRIBUTING] for contribution guidelines, PR checklist and publishing details.
 
-Any change to the policy code must be reflected by a new version. Policies are automatically published on `ghcr.io` if the version is updated.
+Short contributor checklist:
+* Open an issue to discuss non-trivial changes.
+* Bump Policy.yaml version if behaviour changes.
+* Update README, CHANGELOG and example values.
+* Ensure CI passes before merging.
 
 == FAQ
 
-=== Why a monorepo ?
-
-A monorepo simplifies policy discovery and publishing while we build tooling and CI. We may split later if needed.
+=== Why a monorepo?
+A monorepo simplifies discovery, CI and publishing for policy bundles. We may split into multiple repos later as needed.
 
 == Thanks to all the contributors ❤️
 
-link:https://github.com/updatecli/policies/graphs/contributors"[image:https://contrib.rocks/image?repo=updatecli/policies[]]
+link:https://github.com/updatecli/policies/graphs/contributors[image:https://contrib.rocks/image?repo=updatecli/policies[]]
 
-== LINKS
+== Links
 
 * link:https://www.updatecli.io/docs/core/compose/[Updatecli Compose documentation]
 * link:./POLICIES.md[Full Policy list]