chore: apply charmhub review feedback - #34
Merged
danielvnguyen merged 1 commit intoSep 11, 2026
Merged
Conversation
- add SECURITY.md - charmcraft.yaml: added issues, source, contact, title fields - index.html: updated title tag to match charm title - README.md: dropped `--resource app-image=<oci-image>` - LICENSE: fixed copyright
danielvnguyen
requested review from
cardenasse and
srbouffard
and removed request for
a team
September 10, 2026 21:32
minulo
approved these changes
Sep 11, 2026
danielvnguyen
deleted the
chore/address-charmhub-listing-review-feedback
branch
September 11, 2026 00:05
minulo
added a commit
to canonical/gopkg-charmed
that referenced
this pull request
Sep 11, 2026
…g review pattern Mirrors the structure of canonical/bingo#34 (Charmhub listing review feedback) for this repository: 1. CONTRIBUTING.md: added, following bingo's, adapted to this project: contact channels, code of conduct, security reporting, the release-note artifact process this repository actually uses (there is no changelog file), submissions, AI disclosure, CLA and signed commits, and pointers to the CI-tested contribution guides in the documentation instead of duplicating them. 2. charmcraft.yaml: source and issues now use the repository's direct URL (the canonical/gopkg URL redirects), contact gains the public Matrix channel, title is a plain string, and the guidance comment links the current charmcraft.yaml reference. The documentation link stays on the README until the published docs are publicly reachable. 3. SECURITY.md and LICENSE were checked against the template and the source headers: already consistent, no change. 4. Pull request template: the contributing-guide link points at CONTRIBUTING.md, the checklist no longer names a docs/changelog.md that does not exist, and the change-artifact template path is fixed. 5. Documentation home page: the community section no longer claims governance and contribution guides live in root files that did not exist; it links the actual files and pages. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
minulo
added a commit
to canonical/gopkg-charmed
that referenced
this pull request
Sep 15, 2026
…g review pattern Mirrors the structure of canonical/bingo#34 (Charmhub listing review feedback) for this repository: 1. CONTRIBUTING.md: added, following bingo's, adapted to this project: contact channels, code of conduct, security reporting, the release-note artifact process this repository actually uses (there is no changelog file), submissions, AI disclosure, CLA and signed commits, and pointers to the CI-tested contribution guides in the documentation instead of duplicating them. 2. charmcraft.yaml: source and issues now use the repository's direct URL (the canonical/gopkg URL redirects), contact gains the public Matrix channel, title is a plain string, and the guidance comment links the current charmcraft.yaml reference. The documentation link stays on the README until the published docs are publicly reachable. 3. SECURITY.md and LICENSE were checked against the template and the source headers: already consistent, no change. 4. Pull request template: the contributing-guide link points at CONTRIBUTING.md, the checklist no longer names a docs/changelog.md that does not exist, and the change-artifact template path is fixed. 5. Documentation home page: the community section no longer claims governance and contribution guides live in root files that did not exist; it links the actual files and pages. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
minulo
added a commit
to canonical/gopkg-charmed
that referenced
this pull request
Sep 17, 2026
* Adapting the documentation framework from Sphinx * Update .readthedocs.yaml Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update docs/conf.py Co-authored-by: Erin Conley <erin.conley@canonical.com> * Update docs/conf.py Co-authored-by: Erin Conley <erin.conley@canonical.com> * Update docs/conf.py Co-authored-by: Erin Conley <erin.conley@canonical.com> * Update docs/conf.py Co-authored-by: Erin Conley <erin.conley@canonical.com> * docs: address onboarding review feedback * docs: support workflow Python version * Trimmed gitignore, added sphinxcontrib.mermaid to extenstion and pinned the mermaid package * Apply batched suggestions from code review Co-authored-by: Erin Conley <erin.conley@canonical.com> * Adding overwrite_links.js machanism * Get rid of the unused snap and add Juju * Updating wordlist for all 3 layers * Apply review suggestions for the Canonical domain publishing setup Implements erinecon's outstanding suggestions on PR #25: - set the project slug to juju/docs/gopkg-charm - point html_baseurl at the Canonical domain for the built version - name the sitemap doc-sitemap.xml so it does not collide with the site's own sitemap once published there - update the Juju intersphinx target to the juju-cli 3.6 docs - use the project's actual RTD hostname in overwrite_links.js Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Updating the CI/CD to be more specific to the repo * Updating tests so that they are more intuitive and less redundant * Updating the checkout-removed-urls and add a release note * ci(docs): switch to operator-workflows docs_rtd reusable workflow * docs(index): reword sections to satisfy Vale spellcheck * Deleted CLA check * Drop the display name on the release-note compliance job Branch protection on main now requires the check run the upstream reusable workflow actually produces, 'check-change-artifacts / check-release-note-artifact'. The 'name: Validate release note policy' override on this branch renamed that check run to 'Validate release note policy / check-release-note-artifact', so the required check was never reported and the pull request stayed blocked on 'Expected'. With the override gone the file is identical to main. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Updating the docs with actual content * Update .pre-commit-config.yaml Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Fix documentation spellcheck wordlist Co-authored-by: minulo <292215651+minulo@users.noreply.github.com> * Updating the tutorial integration test * Update app/charm/tests/integration/run_full_local_suite.sh Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Updating tests so that they are more intuitive and less redundant * Updating tutorial smoke tests so that the integration test doesn't use stale builds * Update docs/index.rst Co-authored-by: Erin Conley <erin.conley@canonical.com> * docs(conf): apply repo-specific Sphinx title override in content layer * ci: rely on upstream release-note compliance status * Added the publish-facing documentation set and aligned documentation policy checks * Updated docs so that users will not have a migraine over broken tutorial * Changed documentation to remove edge cases. Waiting on tutorial garentees. Uploading for multiple testing at once * Changing the tutorial integration test and update the document * Changing the tutorial integration test and fixed failing URL checks * Documentation ready for public facing. All workflow tested * Fixing spellcheck * Extend tutorial documentation test timeout Co-authored-by: minulo <292215651+minulo@users.noreply.github.com> * Removed skill * Update contributing document * Update so that the documentation now contains only the correct language for Prerequiste sections * Update the language so that it is not meta * Fixing tests that are tied with the documentation update * Extend registry rollout wait and add docs-test failure diagnostics The MicroK8s registry deployment consistently needs more than 5 minutes to become available on GitHub-hosted runners: four addon images pull concurrently on 4 vCPUs and the registry additionally waits for the hostpath provisioner to bind its PVC. Integration tests only touch the registry ~15 minutes after enable (behind the artifact build wait), which is why they pass while every documentation run has timed out. - Raise the registry rollout wait from 5m to 15m in all four guides, matching the 15m the docs already use for juju wait-for. - Print cluster and host state (pods, registry describes, PVCs, node conditions, events, containerd journal, disk) when a docs session fails, so a CI log names the real blocker instead of a bare timeout. - Raise the spread task kill-timeouts to 60m for the longer waits. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Bump MicroK8s to 1.36-strict/stable across docs and concierge The docs-test diagnostics revealed why the registry deployment never becomes ready on GitHub-hosted runners: under MicroK8s 1.31-strict (core20 base, containerd 1.6), every non-root system container (CoreDNS, ingress controller, calico-kube-controllers) dies ~30ms after start on the runners' 6.17 azure kernel, crash-looping forever, while root/privileged pods run fine. Local VMs pass on kernel 6.8, which is why the guides validated locally. The correlation confirms it: the integration suite went red on the commit that pinned concierge to 1.31-strict and is green on commits where concierge computes the newest strict channel. Pin docs, README, reference, and concierge to that channel (1.36-strict/stable) so readers and both CI suites use the same, runner-proven MicroK8s. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Allow LXD bridge traffic past Docker's firewall in docs-test prepare With MicroK8s fixed, the docs jobs reached rockcraft pack for the first time on GitHub runners and failed with 'A network related operation failed in a context of no network access': the runners ship Docker, whose iptables FORWARD policy drops traffic from the LXD instances the craft tools build in. Insert the same guarded DOCKER-USER accept rules for lxdbr0 that charm-ci's build-artifacts workflow uses. On machines without Docker - any reader's fresh VM - the guard makes this a no-op, so the tests still execute only what the guides say. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Wait for MicroK8s readiness before enabling add-ons The tutorial docs-test job caught a startup race: running 'microk8s enable' seconds after 'snap install microk8s' crashes with a Python traceback when the API server is not serving yet, because enable queries cluster state first. The guides enabled add-ons first and only then ran 'microk8s status --wait-ready'. Wait for readiness before enabling (and keep the post-enable wait), in the setup guide, the deploy how-to, and the README quickstart. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Retry the final go-import check until the new hostname is served Both docs-test jobs now execute the guides end to end and failed only on the very last command: the go-import query immediately after 'juju config gopkg-charmed hostname=staging.example.com'. The charm applies config through an in-place pebble restart, so the application barely leaves active status - the juju wait-for guard returns at once and the old hostname can still be served for a few seconds. The tutorial even told readers to 'run the request again' manually. Replace the single query with a retry-until-match loop (two-minute cap) in the tutorial and the hostname how-to, so both readers and CI survive the propagation window. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Add CONTRIBUTING.md and align charm metadata with the Charmhub listing review pattern Mirrors the structure of canonical/bingo#34 (Charmhub listing review feedback) for this repository: 1. CONTRIBUTING.md: added, following bingo's, adapted to this project: contact channels, code of conduct, security reporting, the release-note artifact process this repository actually uses (there is no changelog file), submissions, AI disclosure, CLA and signed commits, and pointers to the CI-tested contribution guides in the documentation instead of duplicating them. 2. charmcraft.yaml: source and issues now use the repository's direct URL (the canonical/gopkg URL redirects), contact gains the public Matrix channel, title is a plain string, and the guidance comment links the current charmcraft.yaml reference. The documentation link stays on the README until the published docs are publicly reachable. 3. SECURITY.md and LICENSE were checked against the template and the source headers: already consistent, no change. 4. Pull request template: the contributing-guide link points at CONTRIBUTING.md, the checklist no longer names a docs/changelog.md that does not exist, and the change-artifact template path is fixed. 5. Documentation home page: the community section no longer claims governance and contribution guides live in root files that did not exist; it links the actual files and pages. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Replace redirecting links with their final URLs Every external link in the reader-facing files was checked; these returned a redirect and now point at the destination directly: - juju.is and microk8s.io marketing hosts -> canonical.com/juju and canonical.com/microk8s - documentation.ubuntu.com/juju/3.6/... -> canonical.com/juju/docs/juju-cli/3.6/... (home page, bug-report issue template, repo-compliance.md) - charmcraft/stable/... -> charmcraft/4/... (home page, explanation) - documentation.ubuntu.com/nginx-ingress-integrator-charm/ -> canonical.com/juju/docs/nginx-ingress-integrator-charm/latest/ - github.com/canonical/gopkg/pull/N -> github.com/canonical/gopkg-charmed/pull/N in the release-note artifacts Left alone on purpose: comment-only links in conf.py and .readthedocs.yaml (scaffold files owned by the lower stack layers) and the vendored charm libraries under app/charm/lib, which are fetched verbatim. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Remove the deploy-locally how-to guide and rechain its documentation test The guide was a strict subset of the tutorial (same commands, no verification), so it duplicated content without adding anything (PR #27 review thread on docs/how-to/deploy-locally-with-microk8s.rst). - Delete the page; redirect its URL to the tutorial in docs/redirects.txt so the removed-URL check stays green. - Drop the how-to guide index entry and the tutorial's read-next link. - The hostname how-to no longer carries a Prerequisites section; it states that it assumes the deployment the tutorial leaves behind. - The how-to-configure-hostname documentation test now chains the setup guide, the tutorial, and the hostname how-to, which is exactly the reader path; the expansion still yields two login sessions with one bootstrap and one add-model. - Update the CI reference page and one explanation sentence that mentioned the removed guide. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Make the setup guide's requirements authoritative and its pathway single Applies the review threads on docs/how-to/set-up-a-local-linux-environment.rst: - State the hardware requirements plainly (AMD64 or ARM64 workstation, 4 CPU cores, 8 GB of RAM, 50 GB of disk) instead of describing them as a tested profile with caveats; the 4 GB memory finding moves to the troubleshooting page. - Present Multipass as the one pathway on Linux, macOS, and Windows, with a native Ubuntu 24.04 LTS host as the only exception, rather than a macOS-specific note. - Drop the step numbers from section titles. - Write AMD64 and ARM64 in prose without code formatting; command output values stay lowercase and code-formatted. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Move ingress procedures into a how-to guide and compact the troubleshooting page Applies the review threads on docs/explanation/ingress.rst, docs/reference/charm-configuration.rst and docs/how-to/troubleshoot-deployment.rst: - New how-to guide 'Configure ingress' takes the procedural sections that were hidden in the explanation page: routing hostname and paths, matching the workload hostname, verifying routing, production DNS, and HTTPS. It assumes the deployment the tutorial leaves behind, so its executable blocks are idempotent and it joins the hostname documentation test chain; the TLS block with placeholder paths is marked SPREAD SKIP. Both upstream integrator references are linked. - The explanation page keeps only concepts (what ingress solves, the components, the integration, why the guides pin the hostname, the two hostname settings, where TLS terminates) and links the how-to guide. - The troubleshooting page uses one-line Symptom and Cause entries, absorbs the ingress failure modes (404, wrong application, 502/503, unresolved hostname, certificate errors) without duplicating the two entries it already had, gains the insufficient-memory cause for Pending pods, and no longer pastes 'newgrp' followed by another command, which the README warns against: logging out and back in is the fix, newgrp is an interactive-only alternative. - The configuration reference lists the single 'hostname' option only, without a back-to-back header, and points at the ingress how-to and the integrator's configuration reference for ingress settings; the set and inspect steps live in the hostname how-to guide. - Section titles in the hostname how-to use the infinitive form. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Restructure the home page to the standard layout and move its deep content to Explanation Applies the review thread on docs/index.rst (follow the standard documentation home page structure) and on docs/explanation/juju-charms-and-rocks.rst (trim upstream duplication): - The home page now carries only what the standard structure asks for: what the charm is, what it does, the need it meets, and who it is for; an 'In this documentation' card grid; how the documentation is organized (Diátaxis); and 'Project and community' with the same real targets the sibling bingo charm uses (code of conduct, security policy, contributing, Discourse support, the Charmhub Matrix room, the issue tracker). - The sections about Go modules, why gopkg.in exists, what the service does (with its diagram) and the go-get query move verbatim into a new explanation page, 'How gopkg.in serves stable import paths', linked from the Explanation index and the home page cards. - 'What the charm adds' merges into the 'What is a charm?' section of the concepts page, which also drops its command summary block and compresses the Juju glossary into one paragraph, relying on the linked upstream documentation for depth. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Restructure the tutorial: unnumbered sections, 'What you'll do', prerequisites Applies the review threads on docs/tutorials/deploy-and-verify-on-kubernetes.rst: - Section titles lose their step numbers; a numbered 'What you'll do' list at the top gives the overview instead, matching the tutorial pattern used across the documentation portfolio. - The 'confirm architecture' section is gone: the prerequisites now state that an AMD64 or ARM64 workstation is required, and every later command already derives the architecture itself. - AMD64 and ARM64 are written in prose without code formatting. The teardown section requested in the same review is deliberately not added yet: the hostname documentation test runs the how-to guides right after the tutorial on the same machine, so the clean-up commands need a SPREAD SKIP decision first (tracked in the local review plan). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Polish the reference, integration-suite, and contribute pages per review Reference: - platforms-and-prerequisites: product name in the description; one sentence for the supported architectures; the tools listed with the snap channels the guides install and the versions the documentation tests last verified (no invented minimums); a detail-oriented lead-in for the add-ons; the Juju model constraints section removed as it duplicated upstream and the tutorial. - ci-workflows: the two sections describing the same workflow merged into one with both intents; the origin and linkage sections rewritten as prose; the trigger list now includes application source changes and the chain description matches the current tests. How-to: - run-full-juju-integration-suite-locally: the 'what this guide validates' material folds into the introduction, the macOS note moves into the prerequisites, the standalone architecture check goes, the PermissionError note links the troubleshooting page instead of repeating it, and the section titles become 'Run the suite with one command' and 'Run the suite manually'. The manual path also waits for MicroK8s readiness before enabling add-ons and enables dns, matching the tested guides. Contribute: - improve-documentation: a single target label (the old file path is still redirected); improve-code: fix the indentation of one command in the Go checks block; index: the suggested description and no section header on a page this short. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Retry the registry readiness check after the add-on rollout The first full run of the rechained documentation test failed on the setup guide's add-on block: 'kubectl rollout status deployment/registry' reported success and the immediately following 'curl http://127.0.0.1:32000/v2/' was refused. On a fast MicroK8s start the registry pod becomes available a few seconds before kube-proxy programs the NodePort, so the check raced ahead of the service. Readers on fast machines hit the same window. The registry check now retries for up to a minute (--retry 30 --retry-delay 2 --retry-all-errors), the same form the hostname how-to already uses for its health check, everywhere the sequence appears: the setup guide, the tutorial prerequisites, the troubleshooting fix block and the manual integration-suite path. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Retry the rock and charm builds in CI when the Ubuntu archive is unreachable The documentation test for the hostname how-to failed twice in a row on the tutorial's build step after the registry check was fixed: once with 'Failed to update packages' (apt-get exit 100) while rockcraft prepared its base instance, once with chisel's 'cannot talk to archive: archive.ubuntu.com ... context deadline exceeded'. The tutorial test ran the identical command on the same commit and passed both times, so the cause is transient reachability of the Ubuntu archive from the LXD build instances on GitHub runners, not the guide. The tutorial now marks the two pack commands SPREAD SKIP and supplies the same commands in an invisible SPREAD block that reruns a failed pack up to three times, thirty seconds apart, as the contribute guide prescribes for a finite CI alternative. The reader-facing block is unchanged apart from a note that a build failing with a network error should simply be run again. A failed pack takes about ten minutes to time out and a green tutorial job has taken forty minutes on a slow runner, so two retries could exceed the tasks' 60-minute kill-timeout; both tasks now allow 90. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Widen the build retry window and the documentation tasks' kill-timeout The first run of the build retry showed two things. Chisel gives up on a slow archive far sooner than apt does (its metadata client times out after 30 seconds, apt's after 120), and once the parts are cached a failed 'rockcraft pack' returns in about a minute, so three attempts thirty seconds apart only cover four minutes of archive trouble. The loop now makes five attempts a minute apart, covering roughly ten. The same run also showed how long a degraded runner network makes an otherwise green job: 'charmcraft pack' alone took an hour and the tutorial job finished at 76 minutes with a single build retry. Both tasks now allow 120 minutes; every step inside still has its own bounded timeout, so this only changes how long a truly stuck run holds a runner. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Point the build instances at the Azure archive mirror on GitHub runners Every documentation test failure since the registry fix has been the same thing: chisel inside the rockcraft build instance cannot fetch InRelease from archive.ubuntu.com before its 30-second metadata timeout, and on a bad day five attempts a minute apart are not enough. apt in the same instance usually succeeds because it waits 120 seconds, and the runner itself never notices because its own apt is configured for the azure.archive.ubuntu.com mirror, which answers in well under a second and serves requests for either Host name. The tasks' prepare step now resolves archive.ubuntu.com and security.ubuntu.com to that mirror in the runner's /etc/hosts. LXD's dnsmasq forwards container lookups to the host resolver, which answers from /etc/hosts, so the build instances that rockcraft and charmcraft launch inherit the mirror without any change to the guides. The step is guarded on the runner's own apt-mirrors.txt naming the Azure mirror, so it is a no-op on a reader's machine, in the same spirit as the DOCKER-USER rules above it. The failure diagnostics now also print how archive.ubuntu.com resolves and how long its InRelease takes to fetch. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Add a clean-up section to the tutorial and run it only at the end of a chain The tutorial now ends by destroying the model it created and, for readers who are done, the controller and the Multipass VM. The two Juju commands are visible and tested; the VM deletion is SPREAD SKIP like the other Multipass steps. The documentation tests chain pages on one machine, and the hostname test continues from the tutorial's deployment into two how-to guides, so the clean-up must not run there. The tutorial marks the start of its clean-up with a new sentinel, '# spread-teardown', from an invisible SPREAD block, and run-docs.sh drops the sentinel and everything after it from every page except the last one in the chain. The tutorial test therefore tears down what it built, and the how-to test keeps the deployment; its expanded script is unchanged. The contribute and CI reference pages describe the sentinel, and the two how-to guides now say they continue from the tutorial's deployment steps rather than from its end. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Run the documentation Makefile from docs/ and name Diátaxis on the contribute page The contribute page told readers to run 'make -C docs ...' from the repository root, which departs from the Sphinx starter pack convention of working inside docs/ and makes every later command longer. Its commands now change into docs/ once and call make directly, as the review suggested for each block. The page also claimed the documentation could be built on Linux or macOS, which read as a platform restriction; it now states what the build actually needs (Git, Make, and Python) and what it does not (the deployment tools). The layout section names Diátaxis and links to it. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Focus the Juju, charms, and rocks page on this project's architecture The page repeated material that the Rockcraft, Charmcraft, and Juju documentation already own: the OCI image standard, what 'rockcraft pack' and 'charmcraft pack' do, the Twelve-Factor methodology, a Juju glossary, and a generic account of which tool is responsible for what. Following the review's worked example for the rock section, each section now says what the piece is for gopkg-charmed, what it contains, and where it lives in the repository, and defers everything else to upstream. The upstream links are now intersphinx cross-references, with Charmcraft and Rockcraft added to intersphinx_mapping next to Juju, so a change to an upstream URL is a one-line fix in conf.py. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Title the how-to guides 'How to ...' and keep the navigation entries short Following the review's convention for how-to guides, every how-to page title now starts with 'How to', and the how-to toctree carries explicit short entries without those two words, so the left-hand navigation does not repeat them. The hostname guide is titled 'How to configure hostname': verifying the go-import metadata is how the goal is checked, not a second goal, so it leaves the title and the navigation entry, and the tutorial's 'What to read next' link matches. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * updating according to the comments * Trim upstream duplication from the gopkg.in and ingress explanations The gopkg.in page opened with a primer on Go modules, restated the version rules that the gopkg.in page itself documents, and explained Go's repository discovery protocol ('?go-get=1'); none of that is ours to maintain. It now says what the service does for this deployment, why the import paths still matter, and the two facts an operator needs (the workload reaches GitHub, and the advertised hostname must be the public one), and links to the Go documentation and the gopkg.in page for the rest. A deployment's own front page redirects to that page. The ingress page described Kubernetes Services, Ingress resources, ingress controllers, and TLS termination in general terms that the Kubernetes documentation owns. It keeps the request diagram and the parts specific to this deployment: what the Go framework extension creates, what the integrator turns into an Ingress resource, the two hostname settings, and why the guides pin the hostname. The ingress how-to no longer repeats the TLS explanation and points to it instead. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Run the documentation tests weekly on Saturday, alongside the integration tests * Keep contributor process off the release-notes index The public release-notes page told readers to follow the HAProxy release-notes naming convention and where the change artifacts live in the repository. Both are contributor process, not release information. The naming rule for rendered release pages now sits in CONTRIBUTING.md next to the artifact workflow it belongs to, without the reference to another project. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Restore the status publisher for the release-note compliance check Branch protection on main requires the status context 'Check for release notes artifact / check-change-artifacts / check-release-note-artifact'. The upstream reusable workflow reports its result as a check run under its own job name, never under that context, so the job that publishes the context as a commit status is the only thing that satisfies the rule. Commit 6ac277e removed it on this branch, which left the required check waiting forever and the pull request blocked even though every job passed. This restores the file exactly as it is on main. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Make the release-notes automation runnable The 'Create release notes' workflow calls canonical/release-notes-automation with inputs that did not exist in the repository: no common.yaml, and a template whose output the script would have written as Markdown under an .rst name. The script also matches release artifacts to change artifacts by the upstream 'pr####.yaml' naming, which the artifacts here did not follow, and the release-artifact template had a typo ('workload_with_version::') that produced the wrong key. Now: common.yaml carries the charm name, channel, and visibility setting; the template is Markdown, as the script produces, and renders a MyST anchor, an HTML meta description, and review notes as comments instead of placeholder text; the change artifacts follow the pr####.yaml convention; the release-artifact template gains the release number the anchor needs; and CONTRIBUTING.md documents both the per-PR artifact and how a release is cut. Verified by rendering a release page with the upstream script from the existing artifacts and building it with Sphinx. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * State the architecture command's output in lowercase code 'dpkg --print-architecture' prints 'amd64' or 'arm64'. The setup guide described that output in capitals after the prose-styling pass; command output keeps its literal form in code formatting, as the same review thread noted. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Record the verified tool versions and the artifacts' own version pins The platforms reference answers the review's question about minimum versions with the two things that are actually known: the versions the documentation tests last passed with (updated to Charmcraft 4.4.2 and now including the Go snap), and the floors the artifacts themselves declare - the ubuntu@24.04 base, Go 1.21 in go.mod, and the ops and paas-charm ranges in the charm's requirements. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Explain the setup guide's steps and drop its repeated checks Address the review of the environment guide on PR #27: say what running the steps on a workstation instead of a VM does (sudo installs, group changes, a cluster listening on ports 80, 443 and 32000) and why a VM helps beyond non-Ubuntu hosts; introduce the tool list with what each tool is for and point at the reference for channels and versions; separate the group membership commands from the installs; state what a successful check looks like instead of "must exit successfully", and move the newgrp caveat into a note that explains the new shell; name the four MicroK8s add-ons and their purpose, and split enabling them from verifying them; describe every output of the final check and remove the checks the reader already ran; reference the Multipass install guide through intersphinx; call the next step a step-by-step tutorial. The executed command sequence is unchanged apart from the removed repeats and the command -v lines merged into one. Assisted by Claude. * Teach the why behind each tutorial step Address the review of the tutorial on PR #27. Orient the prerequisites on what the reader has after the setup guide and state the success criteria of every readiness check. Explain what the experimental-extension variables opt into, what the local registry is and why the tag check fails without a push, how the rock and the charm relate, what a Juju model and the architecture constraint are for, and why an ingress integrator is deployed from Charmhub alongside the local charm; deploy and integrate in separate steps. Set, rather than choose, the ingress hostname, explain why example.com needs no DNS record, name INGRESS_HOST in the lead-in to the integrator configuration and describe what service-hostname, path-routes and rewrite-enabled do. Move the status check into the verification section with --relations and a real transcript, restate the --resolve pinning after the first request, and rename the configuration section to "Update the hostname" with an explanation of what the option controls. Only one executed command was added, juju status --relations; the sample output is fenced so the documentation test does not run it. Assisted by Claude. * Say who deploys what on the home page and drop a duplicate link Juju deploys the charm and the charm runs the rock; the previous sentence had the charm deploying the rock. Remove the contributing-guide bullet from the governance list, which repeats the link in the section above and in "Get involved". Assisted by Claude. * Trim the generic Juju definitions from the architecture page Keep the mapping of this deployment onto Juju's controller, model, applications and units, and leave what a namespace or a pod is to the Juju documentation the cross-references already point at. Assisted by Claude. * Fixing nits * Fixing nits * Fixing tests * Apply batched suggestions from code review Co-authored-by: Erin Conley <erin.conley@canonical.com> * Update docs/explanation/gopkg-service.rst Co-authored-by: Erin Conley <erin.conley@canonical.com> * Apply batched suggestions from code review Co-authored-by: Erin Conley <erin.conley@canonical.com> * Apply the remaining review suggestions on the tutorial and how-to guides Six threads asked for concrete changes that the batched suggestions had not yet picked up: - The home page dropped the paragraph on why published import paths keep needing the service. It reads as reference material on a landing page, and the explanation already makes the same point. - The tutorial links the NGINX ingress integrator to its Charmhub page, shows the sample 'juju status' output with the terminal directive instead of a text code block, and points at the two Go framework extensions that built the rock and the charm. - The setup guide splits 'exit' and 'multipass shell' into separate blocks, because they run in different places and copying them together only runs the first, and lists the four MicroK8s add-ons instead of describing them in one sentence. - The integration-suite guide gives each step its own block so a reader can copy one at a time. The terminal directive exposes its content to Vale, unlike a code block, so the sample output is wrapped in 'vale off' and 'vale on': the controller name and the cloud name in it are literal output, not prose. Verified that the commands the documentation tests execute are unchanged: 'opcli tutorial expand' produces byte-identical output for the setup guide and the tutorial, and differs only by two removed blank lines for the integration-suite guide. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Say what reaches the ingress controller instead of opening with "This" The paragraph began "This works because...", leaving the reader to guess whether it explained the pinned hostname, the Host header, or the address curl connects to. It explains the address: the sentence before it covers why the request must carry the hostname, and this one covers why 127.0.0.1 is somewhere the controller answers. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * Apply the review suggestions I had missed on three more pages A paginated read of the review turned up seven threads beyond the first hundred, on pages the earlier pass never looked at. The hostname how-to now stands on its own. A Prerequisites section states what the guide needs, a deployed and integrated pair of applications with the integrator's service-hostname exported as INGRESS_HOST, instead of leaving the reader to infer it from the tutorial. The introduction says which setting is which: service-hostname decides what reaches the application, hostname is what the workload advertises. The wait step warns that the in-place restart takes a couple of minutes, the generic 'juju config gopkg-charmed' becomes 'juju config gopkg-charmed hostname', and the two verification sections are one. The troubleshooting guide names the commands that show a pod stuck in Pending, rather than describing the symptom without saying where to see it, and its Symptom, Cause, and Fix labels are bold. The CI reference presents the documentation test's behavior as three paragraphs, grouped by when it runs, how it runs, and what it runs. The only command the documentation tests execute differently is the 'juju config' one above, which prints the option's value. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Erin Conley <erin.conley@canonical.com> Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: minulo <292215651+minulo@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does
Applies feedback provided from canonical/charmhub-listing-review#185
SECURITY.md: copied from canonical/is-charms-template-repo, covers what qualifies as a security issue and how to report one via GitHub private security advisories.charmcraft.yaml: addedtitle: bingo — Canonical Pastebin,links.issues,links.source,links.contact(Matrix channel).index.html: updatedtitletag to match charm titleREADME.md: dropped--resource app-image=<oci-image>from the deploy command to match the tutorial's--channel 1/stable(the resource has a default revision in the store).LICENSE: fixed Copyright 2026 Ubuntu → Copyright 2026 Canonical Ltd. to match source file headers.