Skip to content

docs: put warnings before the commands they govern - #166

Merged
aaronmgn merged 1 commit into
mainfrom
doc-fixes-04
Aug 5, 2026
Merged

docs: put warnings before the commands they govern#166
aaronmgn merged 1 commit into
mainfrom
doc-fixes-04

Conversation

@aaronmgn

@aaronmgn aaronmgn commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

Summary

Some warnings come after the commands that they govern. A reader who copies the first command finds the warning too late. This change moves the warnings in front, and makes two hidden requirements into steps.

Details

  • docs/graylog-message-handling.md: the warning about DELETE /api/system/inputs/<id> came after the command block. The warning now comes first.
  • docs/graylog-message-handling.md: the sentence "Raise it if a load balancer targets pod IPs directly ... and raise the grace period with it" put the condition after the instruction, used an unclear "it", and gave two actions together. The text now names endpointPropagationDelaySeconds and terminationGracePeriodSeconds, and gives the condition first.
  • charts/graylog/README.md: the GitOps Secret requirement was a warning block, not a step. It is now step 1 of Pre Installation. The risk of credential rotation is a separate caution.
  • charts/graylog/README.md: added the order of operations for the automatic drain. The preStop hook is part of the pod spec. If you turn on the drain and decrease the replicas in one change, Kubernetes deletes the highest pod with its old spec and drains nothing.
  • charts/graylog/README.md: the uninstall block started with a scale-to-zero command and had no warning. A warning about journals that are not drained now comes first, with a link to the scale-in runbook.
  • .github/ISSUE_TEMPLATE/bug_report.md: added a caution against credentials in a report, and a checkbox for the reporter to confirm redaction.

The text follows the repository's writing conventions: the condition comes before the command, one instruction per sentence, and must or can in place of should.

Linked issues

None.

PR Checklist

Please check the items that apply to your change.

  • Tests added/updated
  • Documentation updated
  • This PR includes a new feature
  • This PR includes a bugfix
  • This PR includes a refactor

Testing Checklist

Static Validation

  • Linter check passes: helm lint ./charts/graylog
  • Helm renders local template sucessfully: helm template graylog ./charts/graylog --validate

--validate needs the MongoDB Operator CRD. The test cluster does not have it. helm template without --validate passes.

Installation

  • Fresh installation completes successfully: helm install graylog ./charts/graylog
  • All pods reach Running state: kubectl rollout status statefulset/graylog
  • Helm tests pass: helm test graylog

Functional (if applicable)

  • Web UI accessible and login works
  • DataNodes visible in System > Cluster Configuration
  • Inputs can be created and receive data

Upgrade (if applicable)

  • Upgrade from previous release succeeds
  • Scaling up/down works correctly
  • Configuration changes apply correctly

The installation, functional, and upgrade tests did not run. A full test of the drain needs a cluster under ingest load.

Specific to this PR

  • The new #scaling-in-safely link resolves.
  • helm lint passes. helm unittest passes: 332 tests in 28 suites.

Notes for reviewers

  • Verify all applicable tests above pass
  • Validate that the linked issues are no longer reproducible, if applicable
  • Sync up with the author before merging
  • The commit history should be preserved - use rebase-merge or standard merge options when applicable

@aaronmgn
aaronmgn requested a review from alix-graylog August 5, 2026 00:54
@aaronmgn aaronmgn self-assigned this Aug 5, 2026
@aaronmgn aaronmgn changed the title docs: put safety warnings before hazards and enforce the chart version gate docs: put safety warnings before the hazards they govern Aug 5, 2026
@CLAassistant

CLAassistant commented Aug 5, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@aaronmgn aaronmgn changed the title docs: put safety warnings before the hazards they govern docs: put warnings before the commands they govern Aug 5, 2026
@aaronmgn
aaronmgn merged commit 5009d5b into main Aug 5, 2026
9 checks passed
@aaronmgn
aaronmgn deleted the doc-fixes-04 branch August 5, 2026 15:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants