Fix doc references to removed files and broken relative links
What does this MR do and why?
The local dry-run instruction in AGENTS.md stops with a LoadError, and several other references in the guides lead nowhere: a plugin and a guide that are gone, and ten links in doc/pipeline_failure_management.md written relative to the wrong directory. This MR updates those references. It changes Markdown only.
| Where | What it said | Why it is stale | Change |
|---|---|---|---|
AGENTS.md, Dry-Running Policies Locally |
Add -r ./plugins/api_observability.rb to get an API call summary |
!4151 (merged) removed the plugin and !4147 (merged) moved the CI jobs to the gem's native --summary and --quiet. The command as written now stops with cannot load such file -- ./plugins/api_observability.rb (LoadError) |
Point to --summary, and say what the --quiet the CI jobs add hides |
AGENTS.md and ARCHITECTURE.md, Plugin System |
api_observability.rb as the example of a plugin that patches the gem |
Same plugin | Use quick_action_filter.rb, which prepends Triage::QuickActionFilter::TriageAdapter to Gitlab::Triage::NetworkAdapters::HttpartyAdapter |
README.md, REACTIVE.md, AGENTS.md |
Links to doc/failure_analysis.md (in AGENTS.md, the path in a row of the Key Documentation table) |
That file never existed on master: 053fd557 renamed the links from doc/failure_categories.md, and !4217 (merged) then removed that guide together with the failure categorization it described |
Remove the README bullet, the "CI/CD Failure Analysis" subsection and the AGENTS.md table row. The Pipeline Failure Management entries stay |
doc/pipeline_failure_management.md |
Ten links written relative to the repository root (REACTIVE.md, triage/triage/pipeline_failure/config/, ...) |
The page has lived in doc/ since it was added in 1065af17, so each of those resolves under doc/ and leads nowhere |
Prefix them with ../, as the back link at the end of the page already is |
The categorization that !4217 (merged) removed now lives in quality-observer, according to its commit message. I removed the entries rather than pointing them there, since I could not tell whether you want these guides to link to another project. If you do, I can add the link.
I did not open an issue for this. I went through the 32 open merge requests: only the draft !4289 touches two of these files. It inserts a section into doc/pipeline_failure_management.md above "Testing and Development" and a line into REACTIVE.md. git merge-tree merges its head with this branch without conflicts.
Related to !4151 (merged), !4147 (merged) and !4217 (merged), the merge requests that removed or replaced what these references pointed at.
Expected impact & dry-runs
The change has no effect on policies, processors or CI. No dry-run applies.
I checked the change in four ways:
- Relative links. I ran a script over every
.mdfile in the tree. It checks every relative link target and every fragment that points at a Markdown heading, and skips fenced code and inline code. Onmasterit reports 12 broken targets: the 10 links above and the README and REACTIVE links todoc/failure_analysis.md. TheAGENTS.mdrow is a path in a table, not a link, so the script cannot see it. On this branch it reports none. - The dry-run command from
AGENTS.md. I ran it offline (--network none) inruby:4.0.6, with the bundle fromGemfile.lock(gitlab-triage1.56.1) and a policy file with no rules. With the old-r ./plugins/api_observability.rbit exits 1 with aLoadError. With--summary, and with--summary --quiet, it exits 0 and prints the API call summary. To see what--quiethides, I also ran one rule over two issues passed in throughOptions#resources, with and withoutquiet: without it the output has the rule's header,Found 2 resourcesand the totals after filtering and limiting, and with it none of those lines appear. - Rendering. I rendered the five files with
gitlab-glfm-markdown0.0.45 and the GLFM options, onmasterand on this branch, and compared the HTML. The only differences are the removed entries, the two reworded plugin bullets, the new dry-run sentence and the../prefixes. - Danger's commit linter.
Gitlab::Dangerfiles::CommitLinterandMergeRequestLinterfromgitlab-dangerfiles4.12.0, the version inGemfile.lock, report no problems for the commit message or this title.
Dry-run output (ruby:4.0.6, gitlab-triage 1.56.1, no network)
$ bundle exec gitlab-triage --debug --dry-run --token "$GITLAB_API_PRIVATE_TOKEN" \
--source-id "gitlab-org/gitlab" --source projects \
--policies-file /policy/empty.yml -r ./plugins/api_observability.rb
bundler: failed to load command: gitlab-triage (/bundle/gems/ruby/4.0.0/bin/gitlab-triage)
/usr/local/lib/ruby/4.0.0/bundled_gems.rb:60:in 'Kernel.require': cannot load such file -- ./plugins/api_observability.rb (LoadError)
exit=1
$ bundle exec gitlab-triage --debug --dry-run --token "$GITLAB_API_PRIVATE_TOKEN" \
--source-id "gitlab-org/gitlab" --source projects \
--policies-file /policy/empty.yml --summary --quiet
******************************************
Executing policies from /policy/empty.yml.
******************************************
Performing a dry run.
======================================================================
API Call Summary
======================================================================
Total HTTP requests: 0
Resources fetched: 0
Rate limit waits: 0
Elapsed time: 0.0s
----------------------------------------------------------------------
======================================================================
exit=0
$ bundle exec gitlab-triage --help | grep -E -- '--summary|--quiet'
--summary Print API call summary at end of execution
--quiet Suppress pagination dots and section headers/policy/empty.yml holds resource_rules: { issues: { rules: [] } }.
One rule (name: probe rule, no conditions, no actions) over two in-memory issues, dry run, quiet unset and then set:
quiet unset:
Performing a dry run.
========================================
Triaging the `gitlab-org/gitlab` project
========================================
---------------------------------------
Processing summaries & rules for issues
---------------------------------------
--------------------------------------------
Gathering resources for rule: **probe rule**
--------------------------------------------
* Found 2 resources...
* Filtering resources...
* Total after filtering: 2 resources
* Limiting resources...
* Total after limiting: 2 resources
quiet set:
Performing a dry run.
Link check on master (bd55740b) and on this branch
master:
checked 41 relative links
REACTIVE.md:438: missing target: doc/failure_analysis.md
README.md:104: missing target: doc/failure_analysis.md
doc/pipeline_failure_management.md:47: missing target: triage/triage/pipeline_failure/config/
doc/pipeline_failure_management.md:74: missing target: triage/processor/engineering_productivity/pipeline_health/pipeline_failure_management.rb
doc/pipeline_failure_management.md:86: missing target: triage/triage/pipeline_failure/config/
doc/pipeline_failure_management.md:179: missing target: REACTIVE.md
doc/pipeline_failure_management.md:180: missing target: SCHEDULED.md
doc/pipeline_failure_management.md:196: missing target: REACTIVE.md
doc/pipeline_failure_management.md:219: missing target: REACTIVE.md
doc/pipeline_failure_management.md:223: missing target: REACTIVE.md
doc/pipeline_failure_management.md:241: missing target: REACTIVE.md
doc/pipeline_failure_management.md:267: missing target: REACTIVE.md
this branch:
checked 39 relative linksAction items
None of the template's items apply: the change adds no environment variable and changes no behavior.