Skip to content

Add FAQ section with troubleshooting checklists#3404

Merged
pfefferle merged 1 commit into
trunkfrom
add/troubleshooting-faq
Jun 12, 2026
Merged

Add FAQ section with troubleshooting checklists#3404
pfefferle merged 1 commit into
trunkfrom
add/troubleshooting-faq

Conversation

@pfefferle

Copy link
Copy Markdown
Member

Proposed changes:

  • Add a new docs/faq/ section with checklists for the two most common support topics, distilled from recurring wordpress.org support threads and GitHub issues:
    • Why is a follow request stuck on "pending"? — splits triage into inbound causes (host mod_security rules, REST-restricting security plugins, caching/Cloudflare, signature 401s, the Disallowed Comment Keys list) and outbound causes (WP-Cron, blocked outgoing requests), including a ready-to-send host-escalation template and Mastodon delivery-failure-tracking recovery.
    • Why don't comments from the Fediverse show up? — Spam/Pending/Trash first, then the captcha/antispam plugin class (hCaptcha, Advanced Google reCAPTCHA, WP Armour, CleanTalk, Akismet quirks), silently-discard options, and protocol semantics (mentions without inReplyTo).
  • Cross-link the new section from docs/readme.md, docs/how-to/readme.md and the readme.txt FAQ.
  • Every cause listed is backed by maintainer-confirmed forum threads or GitHub issues and was verified against the current code paths (Moderation disallowed-list check, Interactions::persist() comment pipeline, auto-accepted follows).

Other information:

  • Have you written new tests for your changes, if applicable? (not applicable, documentation only)

Testing instructions:

  • Read both new guides in docs/faq/ and check the advice against your support-thread experience.
  • Verify the relative links between docs/faq/, docs/how-to/ and the GitHub links in readme.txt resolve.

Two new guides distilled from recurring support-forum threads and GitHub
issues: follow requests stuck on pending, and comments from the
Fediverse not showing up (captcha/antispam plugins and friends).
Copilot AI review requested due to automatic review settings June 12, 2026 14:35
@pfefferle pfefferle added the Docs label Jun 12, 2026
@pfefferle pfefferle self-assigned this Jun 12, 2026
@pfefferle pfefferle requested a review from a team June 12, 2026 14:35

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Pull request overview

This PR adds a new troubleshooting-oriented FAQ documentation section and links to it from existing user-facing docs/readmes, to make the most common support resolutions easier to find.

Changes:

  • Add docs/faq/ with two checklist-style troubleshooting guides (pending follows; missing federated comments).
  • Cross-link the new FAQ section from docs/readme.md, docs/how-to/readme.md, and the plugin readme.txt.
  • Add a patch-level changelogger entry announcing the new FAQ guides.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

Show a summary per file
File Description
readme.txt Updates the “How do I solve…” FAQ pointer to include the new docs FAQ section and examples.
docs/readme.md Adds a top-level “FAQ” section linking to the new troubleshooting docs.
docs/how-to/readme.md Cross-links to the FAQ for “something broken” troubleshooting before configuration guides.
docs/faq/readme.md Introduces the FAQ landing page and table of contents.
docs/faq/pending-follow-requests.md New troubleshooting checklist for diagnosing pending follow requests (inbound vs outbound).
docs/faq/missing-comments.md New troubleshooting checklist for missing federated comments (queues, captcha/antispam, inbox blocking, semantics).
.github/changelog/add-troubleshooting-faq Changelogger entry for the added FAQ guides.

@pfefferle pfefferle merged commit 6b9f1c0 into trunk Jun 12, 2026
8 checks passed
@pfefferle pfefferle deleted the add/troubleshooting-faq branch June 12, 2026 14:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants