docs: put warnings before the commands they govern - #166
Merged
Conversation
22 tasks
alix-graylog
approved these changes
Aug 5, 2026
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
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.
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 aboutDELETE /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 namesendpointPropagationDelaySecondsandterminationGracePeriodSeconds, 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
mustorcanin place ofshould.Linked issues
None.
PR Checklist
Please check the items that apply to your change.
Testing Checklist
Static Validation
helm lint ./charts/grayloghelm template graylog ./charts/graylog --validate--validateneeds the MongoDB Operator CRD. The test cluster does not have it.helm templatewithout--validatepasses.Installation
helm install graylog ./charts/graylogkubectl rollout status statefulset/grayloghelm test graylogFunctional (if applicable)
Upgrade (if applicable)
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
#scaling-in-safelylink resolves.helm lintpasses.helm unittestpasses: 332 tests in 28 suites.Notes for reviewers