Skip to content

docs: fix broken contribution guide links and forwarder#26016

Open
pmenic wants to merge 8 commits intogoogle-gemini:mainfrom
pmenic:fix/issue-25488-broken-contributing-links
Open

docs: fix broken contribution guide links and forwarder#26016
pmenic wants to merge 8 commits intogoogle-gemini:mainfrom
pmenic:fix/issue-25488-broken-contributing-links

Conversation

@pmenic
Copy link
Copy Markdown
Contributor

@pmenic pmenic commented Apr 26, 2026 •
edited
Loading

Closes #25488 (and a related 404 found while investigating).

Summary

Three small docs changes that fix two genuinely-broken user-visible links plus one lychee InvalidPathToUri warning in CONTRIBUTING.md.

When I started investigating #25488 the original CI failure had already self-resolved (lychee v2.6.1 now treats the /docs/... paths as warnings rather than errors), but the underlying issues are real and visible to users browsing the docs on GitHub:

Path Before After
CONTRIBUTING.md:416 (React DevTools image) ![](/docs/assets/connected_devtools.png) — renders on GitHub but generates [WARN] InvalidPathToUri from lychee. No alt text ![Connected React DevTools](docs/assets/connected_devtools.png) — file-relative path, lychee accepts it, alt text added
docs/CONTRIBUTING.md Git symlink pointing at ../CONTRIBUTING.md. On GitHub's web view it rendered as literal text ../CONTRIBUTING.md (not a clickable link) and breaks on Windows checkouts that lack symlink support Regular markdown file forwarding to the root CONTRIBUTING.md with a clickable link
docs/index.md:127 (Contribution guide link) [Contribution guide](/docs/contributing) — GitHub 404 (the path doesn't exist; the file is CONTRIBUTING.md at repo root) [Contribution guide](../CONTRIBUTING.md) — works on GitHub blob view

What I verified visually

  • ✅ Old [Contribution guide](/docs/contributing) from docs/index.md returns "File not found" on GitHub
  • ✅ Old docs/CONTRIBUTING.md symlink rendered as literal text "../CONTRIBUTING.md" in the Preview tab on github.com instead of a working link
  • ✅ The CONTRIBUTING.md image renders correctly on GitHub both before and after the fix (the change is hygiene + lychee cleanliness, not a visible regression)

On the other 3 links from the issue

The original issue listed 4 errors. By the time I picked it up, only the image at CONTRIBUTING.md:416 was still generating a lychee warning; the other three (/docs/faq.md, /docs/integration-tests.md, /docs/sidebar.json) no longer trigger errors with the current lychee version (v2.6.1). I focused on what's still observably broken today + the related 404 in docs/index.md.

Pre-merge checklist

  • docs/ content updated and verified to render correctly on GitHub
  • No code changes — pure docs/markdown
  • Validated the converted docs/CONTRIBUTING.md renders as a proper markdown page (not a symlink target dump)
  • CLA signed by @pmenic — will sign on first PR push if not already

@pmenic
docs: fix broken contribution guide links and forwarder
fefde38 
Three small changes addressing google-gemini#25488 and a related broken link found while
investigating:

- CONTRIBUTING.md: replace the absolute `/docs/...` path on the React
  DevTools image with a file-relative path, and add proper alt text.
  The previous form generated `[WARN ] InvalidPathToUri` from lychee.
- docs/CONTRIBUTING.md: replace the symlink with a regular markdown
  forwarder. The symlink rendered as literal `../CONTRIBUTING.md` text
  in GitHub's blob view (see screenshot in PR) and is unreliable on
  Windows checkouts that don't have symlink support enabled.
- docs/index.md: fix the "Contribution guide" link in the Development
  section. It pointed to `/docs/contributing`, which 404s on GitHub
  (the file is `CONTRIBUTING.md` at repo root). Now points to
  `../CONTRIBUTING.md`.
@pmenic pmenic requested review from a team as code owners April 26, 2026 20:46
@gemini-code-assist
Copy link
Copy Markdown
Contributor

gemini-code-assist Bot commented Apr 26, 2026

Summary of Changes

Hello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses several documentation issues, specifically targeting broken links and rendering problems on GitHub. By replacing problematic symlinks and correcting incorrect file paths, the changes ensure that contributors can reliably access the contribution guide and that documentation assets render correctly across different environments.

Highlights

  • Broken Link Fixes: Corrected broken documentation links in docs/index.md and updated the contribution guide forwarder in docs/CONTRIBUTING.md to ensure proper navigation.
  • Image Accessibility and Pathing: Updated the React DevTools image path in CONTRIBUTING.md to a file-relative format and added descriptive alt text to improve accessibility and resolve CI warnings.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

@gemini-cli gemini-cli Bot added the area/documentation Gemini CLI documentation tasks and issues label Apr 26, 2026
gemini-code-assist[bot]
gemini-code-assist Bot reviewed Apr 26, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

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

Code Review

This pull request updates documentation links and metadata across the repository. Key changes include adding alt text to an image in the root CONTRIBUTING.md, converting docs/CONTRIBUTING.md from a simple path reference to a descriptive link, and updating the contribution guide link in docs/index.md to point directly to the root file. I have no feedback to provide.

Note: Security Review has been skipped due to the limited scope of the PR.

@pmenic pmenic mentioned this pull request Apr 26, 2026
Merged
4 tasks
This was referenced Apr 27, 2026
Open
Open
Bojun-Vvibe added a commit to Bojun-Vvibe/oss-contributions that referenced this pull request Apr 27, 2026
@Bojun-Vvibe
review: drip-104 batch B (gemini-cli + litellm + goose)
7c89c84 
- google-gemini/gemini-cli#26016 docs: contribution-guide link fixes (merge-as-is)
- google-gemini/gemini-cli#25974 fix: file-loaded theme lookup by internal name (merge-after-nits)
- BerriAI/litellm#26575 OAuth discovery extension + route deauthing (needs-discussion)
- aaif-goose/goose#8856 chore: dependabot auto-merge workflow (merge-after-nits)
@pmenic
Copy link
Copy Markdown
Contributor Author

pmenic commented Apr 30, 2026

Heads up on the red CI on the previous SHA (4a2a7768): it was a real bug in this PR, not infra. Pushed a one-commit fix in 5a8eb7a and would appreciate a workflow re-run.

Root cause. When I converted docs/CONTRIBUTING.md from a symlink to a regular markdown forwarder, I updated the blob content but the index entry was left at mode 120000 (symlink) instead of 100644 (regular file). On Windows that's invisible (NTFS materializes it as a normal file), but on the Linux CI runners git checks it out as a symlink whose target string is the markdown text — i.e. a broken symlink. Every step that does stat() on docs/CONTRIBUTING.md then fails with ENOENT, starting at npm install (the prepare script runs husky && npm run bundle, which reads that file). That cascaded into the Lint / Bundle Size / Test (Linux+Mac) / Slow Win / E2E failures you saw.

Fix. Pure mode change, blob SHA unchanged:

:120000 100644 3459be5c1 3459be5c1 T  docs/CONTRIBUTING.md
 mode change 120000 => 100644 docs/CONTRIBUTING.md
 1 file changed, 0 insertions(+), 0 deletions(-)

Unrelated: the linkChecker (Links workflow) failure on the previous run is an infra issue with lycheeverse/lychee-action (Error: Cannot parse inputs from arguments) — same symptom on other PRs against current main. Not introduced here.

The new commit needs a maintainer to approve the workflow run for it to start (fork-PR action_required). Thanks!

@pmenic
Copy link
Copy Markdown
Contributor Author

pmenic commented May 4, 2026

Pushed a3cfa7c54 — Prettier fix for docs/CONTRIBUTING.md (the forwarder line was 96 chars, violating proseWrap: "always" + printWidth: 80 for markdown). Verified locally with both npx prettier --check docs/CONTRIBUTING.md and the full node scripts/lint.js --prettier (clean). New head needs the standard fork-PR workflow approval. Thanks!

@gemini-cli
Copy link
Copy Markdown
Contributor

gemini-cli Bot commented May 4, 2026

Hi there! Thank you for your interest in contributing to Gemini CLI.

To ensure we maintain high code quality and focus on our prioritized roadmap, we only guarantee review and consideration of pull requests for issues that are explicitly labeled as 'help wanted'.

This PR will be closed in 7 days if it remains without that designation. We encourage you to find and contribute to existing 'help wanted' issues in our backlog! Thank you for your understanding.

@g-samroberts g-samroberts self-assigned this May 6, 2026
@g-samroberts g-samroberts removed their assignment May 7, 2026
@jkcinouye jkcinouye self-assigned this May 8, 2026
@gemini-cli gemini-cli Bot added the priority/p3 Backlog - a good idea but not currently a priority. label May 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer

@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments

Reviewers whose approvals may not affect merge requirements

At least 1 approving review is required to merge this pull request.

Assignees

@jkcinouye jkcinouye

Labels

area/documentation Gemini CLI documentation tasks and issues priority/p3 Backlog - a good idea but not currently a priority. status/pr-nudge-sent

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

docs: Fix 4 broken links in docs/CONTRIBUTING.md

3 participants

@pmenic @jkcinouye @g-samroberts