docs: update the readme by cbartz · Pull Request #195 · canonical/github-runner-operators

cbartz · 2026-04-30T09:07:09Z

What this PR does

Update the README with purpose and structure of the repo, and move Grafana dashboard conventions to a new reference doc page.

Why we need it

The README is not providing a lot of information and is still marking the repo as WIP, though the charms are already used in production.

Checklist

Copilot

Pull request overview

Updates repository documentation to better explain the repo’s purpose/structure and adds a reference page documenting Grafana dashboard locations and conventions.

Changes:

Refresh README.md to describe the repo and provide an updated directory layout.
Add new reference doc for Grafana dashboards and link it from the reference index.
Update docs/reference/index.rst to include the new reference page in the toctree.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
`README.md`	Replaces WIP README content with a purpose statement, updated repo layout, and pointer to `docs/`.
`docs/reference/index.rst`	Adds `grafana-dashboards` to the reference toctree.
`docs/reference/grafana-dashboards.md`	New reference page describing dashboard directories and JSON conventions.

Copilot · 2026-04-30T09:10:15Z

+## Further information

-Dashboard JSON files should use `__inputs` to declare the datasource (type `prometheus`).
-Setting `"editable": false` is recommended for clarity, but is not strictly required:
-dashboards delivered through `cos-configuration-k8s` are filesystem-provisioned and
-therefore read-only in Grafana regardless of the JSON flag. Metric names follow the
-[OpenTelemetry hostmetrics receiver](https://opentelemetry.io/docs/collector/components/#receiver)
-Prometheus naming convention (e.g. `system_cpu_time_seconds_total`).
+Further information can be found in the `docs/` directory.


A new doc page is being added under docs/reference/, but docs/changelog.md wasn’t updated. Please add a short changelog entry noting the new reference page so documentation consumers can track user-facing doc changes.

the changelog currently only refers to planner and webhook-gateway charm. should we change the changelog to reflect everything user-facing in this repo? @erinecon

Yes, I think so -- the changelog should cover everything relevant to users

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

cbartz · 2026-04-30T10:12:54Z

-JSON files from this Git repository and provisions them via the `grafana-dashboard`
-relation. Provisioned dashboards are **immutable** in Grafana regardless of user
-role — they cannot be edited or deleted through the UI.
+docs/                       # Documentation


I have removed this, because I do not think we should mention deployment details here.

erinecon

Thanks for updating the README!

erinecon · 2026-04-30T13:21:21Z

+## Further information

-Dashboard JSON files should use `__inputs` to declare the datasource (type `prometheus`).
-Setting `"editable": false` is recommended for clarity, but is not strictly required:
-dashboards delivered through `cos-configuration-k8s` are filesystem-provisioned and
-therefore read-only in Grafana regardless of the JSON flag. Metric names follow the
-[OpenTelemetry hostmetrics receiver](https://opentelemetry.io/docs/collector/components/#receiver)
-Prometheus naming convention (e.g. `system_cpu_time_seconds_total`).
+Further information can be found in the `docs/` directory.


Yes, I think so -- the changelog should cover everything relevant to users

erinecon · 2026-04-30T13:24:33Z

WDYT about adding a link to the RTD site somewhere in the README, or a dedicated section about the documentation? Currently we use this template section for most of our repos with RTD projects:

## Documentation Our documentation is stored in the `docs` directory. It is based on the Canonical starter pack and hosted on [Read the Docs](LINK TO RTD). In structuring, the documentation employs the [Diátaxis](https://diataxis.fr/) approach. You may open a pull request with your documentation changes, or you can [file a bug](LINK TO ISSUES) to provide constructive feedback or suggestions. To run the documentation locally before submitting your changes: ```bash cd docs make run ``` GitHub runs automatic checks on the documentation to verify spelling, validate links and style guide compliance. You can (and should) run the same checks locally: ```bash make spelling make linkcheck make vale make lint-md ```

erinecon · 2026-04-30T13:30:45Z

 charms/
  planner-operator/         # Juju charm: GitHub runner planner
    cos_custom/
      grafana_dashboards/   # Grafana dashboards for the planner charm
-                            # (served via cos-configuration-k8s, path: charms/planner-operator/cos_custom/grafana_dashboards)
  webhook-gateway-operator/ # Juju charm: GitHub webhook gateway


Do you think the README should provide any descriptions or high-level overview of the roles/responsibilities fulfilled by the charms? I think that the layout block is already clear about the structure, but consider adding a new section after the layout (maybe something like ## Charms or ## Repository charms) with some brief details about the purpose of the charms.

erinecon · 2026-04-30T13:33:41Z

+  webhook-gateway/          # Application entry point: webhook gateway

-## Observability: Grafana dashboards
+internal/                   # Shared Go packages


I ran the README draft through Gemini and asked for feedback about how digestable the README is for LLMs. Gemini said that it's not clear what the internal folder actually holds -- what kind of logic exists in this folder? Perhaps clarifying the purpose in this block may help, something like:

Suggested change

internal/ # Shared Go packages

internal/ # Shared Go packages to <fulfill this specific purpose>

That way you don't need to provide more details or an explicit section

cbartz added 3 commits April 30, 2026 09:33

docs: Add readme intro

25c7dae

docs: update repository layout and remove observability section

107e1db

docs: move Grafana dashboard reference to docs/reference

5fdfb77

cbartz requested a review from Copilot April 30, 2026 09:07

Copilot started reviewing on behalf of cbartz April 30, 2026 09:07 View session

Copilot AI reviewed Apr 30, 2026

View reviewed changes

cbartz added 2 commits April 30, 2026 11:17

docs: fix review comments - capitalize Juju and replace e.g.

9daeb09

docs: fix spelling and broken link in grafana-dashboards reference

31595c4

cbartz requested a review from Copilot April 30, 2026 09:48

Copilot started reviewing on behalf of cbartz April 30, 2026 09:48 View session

Copilot AI reviewed Apr 30, 2026

View reviewed changes

Comment thread README.md

Comment thread README.md

Comment thread README.md

Comment thread docs/reference/grafana-dashboards.md Outdated

Comment thread docs/reference/grafana-dashboards.md

docs: fix host metrics receiver link to point to correct source

8c5952b

cbartz commented Apr 30, 2026

View reviewed changes

cbartz marked this pull request as ready for review April 30, 2026 10:13

cbartz requested review from florentianayuwono, javierdelapuente, weiiwang01, yanksyoon and yhaliaw as code owners April 30, 2026 10:13

cbartz requested a review from erinecon April 30, 2026 10:13

florentianayuwono approved these changes Apr 30, 2026

View reviewed changes

yanksyoon approved these changes Apr 30, 2026

View reviewed changes

erinecon added the documentation Improvements or additions to documentation label Apr 30, 2026

erinecon reviewed Apr 30, 2026

View reviewed changes

Merge branch 'main' into docs/update-readme-ISD-5404

f3da639

	internal/ # Shared Go packages
	internal/ # Shared Go packages to <fulfill this specific purpose>

Conversation

cbartz commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does

Why we need it

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

cbartz Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

erinecon Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cbartz Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

erinecon left a comment

Choose a reason for hiding this comment

Uh oh!

erinecon Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

erinecon Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

erinecon Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

erinecon Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

cbartz commented Apr 30, 2026 •

edited

Loading