Skip to content

📖 docs: explain how to edit hive.yaml - #19188

Merged
hivecommons-hive[bot] merged 1 commit into
hivecommons:v5from
Karibhou:docs/hive-yaml-19187
Nov 19, 2026
Merged

hivecommons-hive[bot] merged 1 commit into
hivecommons:v5from
Karibhou:docs/hive-yaml-19187

Conversation

@Karibhou

Copy link
Copy Markdown
Contributor

Fixes #19187

What changed

  • Add an Operations guide for locating and editing the persisted hive.yaml on Kubernetes, Podman, Docker Compose, and native macOS/Linux.
  • Explain what hosted dashboard owners can change, how raw YAML differs from the effective JSON export, and why review.analysis_factcheck needs a deployment operator.
  • Document validation, reload versus restart, and the layers that can mask a change. Link the guide from TechDocs, Settings, the operator reference, and the configuration references.

Verification

Docs only; no runtime tests. Checked paths, precedence, menu labels, the hive validate command, and reload behavior against the v5 manifests and source. Checked existing Markdown link targets and section anchors.

-- hive: backend=omp model=openai-codex/gpt-6.2-sol

Locate the persisted YAML by deployment, explain dashboard exports and
Settings coverage, and show how to validate and apply manual changes.

Hive-Run: hivecommons#19187
Hive-Plan: Editing hive.yaml operator guide
Hive-Spec: hivecommons#19187
Co-authored-by: Nate W <4453979+nate-double-u@users.noreply.github.com>
Signed-off-by: Karibhou <157208370+Karibhou@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 19, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign hanthor for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Nov 19, 2026
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#19110 🐛 Filter em-dashes on every outbound path, agent proxy writes included same files src/docs/documentation-map.md
#19143 🐛 Reviewer-stated rules: ignore quotes and questions, match more future phrasings, and give the preferences a Settings card same files src/docs/api-reference/configuration.md
src/docs/settings.md

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Intent-alignment: the PR covers the four gaps in #19187 (location per deployment, hosted/no-shell guidance incl. review.analysis_factcheck as YAML-only, reload vs restart, layers/export/download) and links the guide from techdocs-assessment.md, as the issue asked. I checked the new relative links and the #configuration-blocks, #config-export-is-not-a-backup and fact-check anchors at the merge base; they resolve. Docs only; no scope creep.

Advisory (non-blocking):

  • src/docs/settings.md:7 - the existing pointer to config-layering.md ("which file a saved setting is written to") was replaced rather than supplemented. The new guide links to it, so it is still reachable, but the Settings page no longer answers that question directly. Consider keeping both links.
  • src/docs/editing-hive-yaml.md - issue item 2 asked for a list of keys Settings covers; the guide gives examples plus the parity allowlist and says it is not an exact list. That is an honest answer, but it is a partial one.

-- hive: agent=adjudicator-3 backend=claude model=claude-sonnet-5-5 claude=2.1.327

@hivecommons-hive

hivecommons-hive Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

Review follow-ups: 1 open of 1 (below review.backlog.min_severity: P2)

Non-blocking findings below the backlog filing line, listed here instead of as issues. Tick them off as they are fixed; set review.backlog.min_severity: P3 to file every finding.

  • P3 info intent-alignment — No exhaustive list of Settings-covered keys (src/docs/editing-hive-yaml.md:19): Issue item 2 asked which keys Settings covers; the guide gives examples and the parity allowlist, and says no exact list exists.

stage 095-pre-merge-soak → 060-reviewed: untrusted-author-role

Ready for a human merge: verdict approved 1652a0b, 67/67 checks green, DCO yes, soak 10m0s elapsed. Blocked only by role/untrusted (no trusted-author role).

The hive never approves on your behalf: /lgtm /approve (or merge) if you accept it.

Evidence bundle `#191881652a0b` sha256:c68c9cac6f2d494a85b582ccee5c06d16995248bdb37a468adb4266c54e7d282 — download from the dashboard or `hivectl review evidence #19188`.

@nate-double-u

Copy link
Copy Markdown
Contributor

This closes most of #19187. Two contradictions remain in pages the PR doesn't touch, and settings.md loses a link.

What it fixes

  • Location per deployment: Kubernetes, Podman, Compose and native are all covered in one table.
  • One entry point: linked from Settings, the operator reference, config-layering, the API reference, TechDocs and the documentation map.
  • Hosted owners with no shell: covered. review.analysis_factcheck is called out as YAML-only, with what to send the operator.
  • Reload vs restart, and masking layers: covered. The example of review being taken whole from the overlay is a good one.

Fix in this PR or a follow-up

  1. Troubleshooting still contradicts the new guide. troubleshooting.md ("Config fails to load or save") says that on Kubernetes you edit the ConfigMap/Secret source and restart the pod. The new guide and manual-provisioning.md ("Config precedence") say ConfigMap edits after first boot do nothing. Reword that sentence or point it at the new page. Link the guide from that section too, since it is where readers land when a config fails to load.
  2. manual-provisioning.md gives conflicting edit targets.
    • The "ConfigMap edits have no effect" row in the failure-mode table says to edit /data/hive.yaml.dashboard.
    • "Config precedence" says editing only .dashboard is not a later-boot repair, because .runtime wins.
    • The new guide says to edit .runtime, and the overlay too when it supplies an overriding block.
    • The "deliberate reseed" bullet (clear .runtime/.bak after a backup) also sits awkwardly next to the guide's "do not delete either file". Please reconcile all of these.
  3. settings.md replaces a link instead of adding one. The pointer to config-layering.md ("which file a saved setting is written to") is gone. Keep both. Agree with the bot's note.

Suggestions (non-blocking)

  • Step 3 says to validate "in the same environment" but doesn't show how to get there. Add the one-liners already in Troubleshooting: kubectl -n <ns> exec deploy/hive -- hive validate, docker compose exec hive hive validate, podman exec hive hive validate.
  • For dashboard-only hosted owners, say who "the hosting operator" is on the hosted hub and how to reach them.
  • Check that the docs site sidebar picks up the new page. The Operations nav doesn't list config-layering today, so a nav entry may be needed in hivecommons/docs.
  • Agree with the bot that the partial Settings key list is honest. The dotted-key search tip is a reasonable answer.

I read the diff against the published docs only. I did not verify paths, hive validate or reload behavior against the code.


Review drafted by Claude (Anthropic) and edited by @nate-double-u. Checked against the diff and published docs only, not against code behavior.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

/lgtm

Posted by @clubanderson from the Hive dashboard; the merge gate decides from here.

@kubestellar-prow

Copy link
Copy Markdown
Contributor

@hivecommons-hive[bot]: changing LGTM is restricted to collaborators

Details

In response to this:

/lgtm

Posted by @clubanderson from the Hive dashboard; the merge gate decides from here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

/approve

Posted by @clubanderson from the Hive dashboard; the merge gate decides from here.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved by @clubanderson for Hive auto-merge on green CI.

Approved from the Hive dashboard by @clubanderson as the owner decision on a Ready-for-human-merge pull request; hive merges it on its next merge pass once CI is green.

@hivecommons-hive hivecommons-hive Bot added the lgtm Indicates that a PR is ready to be merged. label Nov 19, 2026
@hivecommons-hive
hivecommons-hive Bot merged commit d048cd1 into hivecommons:v5 Nov 19, 2026
86 of 87 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates the PR's author has signed the DCO. lgtm Indicates that a PR is ready to be merged. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

📖 docs: where is hive.yaml and how do I edit it by hand?

2 participants