Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

[Docs audit] Missing pages: package-based first backup tutorial, verify-a-backup, upgrade guide, error index; IA problems

Aperta
  • Qualcosa non va?
#528 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
25/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
docker, linux, mysql
Ambito
databases, documentation

Direzione di ricerca

Start with the nav in mkdocs-base.yml around lines 195-196, where upgrade.md is commented out, then read the 8.4 quickstart-overview and verify-backup pages the finding cites. The issue spans several new pages (first backup, verify, upgrade, error index) and a nav restructure across 8.0, 8.4 and 9.7, so agree the scope with maintainers before writing. Done means the new pages render, the nav links resolve, and the tutorial steps have been run on a package install.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Found during a hands-on audit of the Percona XtraBackup docs (2026-10-12): every page was executed as written on Ubuntu 24.04, Ubuntu 26.04, Debian 13, Rocky 9 and Rocky 10 (SELinux enforcing) with PXB 8.0.35-36, 8.4.0-7 and 9.7.1-rc1 against Percona Server 8.0.46/8.4.11/9.7.2 and Oracle MySQL 8.0.46/8.4.11/9.7.2, with data and a concurrent write load; the rendered sites were also crawled and link-checked. Source references are <branch>:docs/<file>.md:<line> (branches 8.0 @6145834, 8.4 @5d943a6, 9.7 @5aff2c7). Finding IDs (D1-D70) are shared across the issues of this audit:

Where each finding is filed
Issue Findings
#512 D30, D31, D40, D41
#513 D1, D53, D64
#514 D2, D19
#515 D44, D45
#516 D5
#517 D32, D47, D61, D28
#518 D17, D12, D18, D38
#519 D6, D35, D27, D24
#520 D14, D26, D29, D33, D23
#521 D3, D7, D4, D8
#522 D9, D10, D11, D34, D39, D62
#523 D20, D21, D22, D36, D15, D42, D43, D49, D37
#524 D13, D16
#525 D54, D55, D56, D57, D58, D59, D63
#526 D60, D51, D52
#527 D46, D50
#528 D65, D66, D67
#529 D68, D69, D70, D48, D25

Findings in this issue: D65 (Medium), D66 (Medium), D67 (Low)

D65. No package-based first-backup tutorial, and the verification guidance is weak and misplaced

  • Severity: Medium
  • Series: 8.0, 8.4, 9.7
  • Pages: 8.4/quickstart-overview (Docker only); 8.4/verify-backup (filed under "Replicate")
  • Fix:
    • Add the tutorial "Your first backup and restore (packages)": install, then minimal user, backup, prepare, restore (D30), verify.
    • Add a "Verify a backup" page with three levels:
      1. Prepare succeeded and backup_type = full-prepared.
      2. Start a throw-away mysqld on a copy, then run mysqlcheck and CHECKSUM TABLE.
      3. Replica plus pt-table-checksum.
    • Mention --check-tables.
    • Move verification into "Restore".

D66. No upgrade guide; troubleshooting is thin; there is no error index

  • Severity: Medium
  • Series: 8.4, 9.7
  • Pages: nav mkdocs-base.yml:195-196 (upgrade.md is commented out; /8.4/upgrade.html returns 404); the exit-codes page is two sentences
  • What happened:
    • Packages conflict: 84 vs 80 (site crawl), and 97 vs 84 (Rocky 10 run).
    • Nothing explains how to prepare old backups after a server major upgrade.
    • The 8.0 error-message index has no 8.4 or 9.7 equivalent.
  • Fix:
    • Add an "Upgrade Percona XtraBackup" page:
      1. Upgrade PXB in the same window as the server.
      2. Swap the repo and the package.
      3. Take a fresh full backup after the upgrade.
      4. Prepare old backups with the old PXB, using a tarball or a Docker image.
      5. Note that incremental chains cannot cross the upgrade.
    • Add an error-message troubleshooting index. lists the candidate messages.

D67. Information architecture problems

  • Severity: Low
  • Series: 8.0, 8.4, 9.7
  • What happened:
    • The restore pages are scattered across the nav.
    • "Encrypted InnoDB tablespace backups" sits under xbcrypt encryption, though the two are different features.
    • There is no "choose a backup method" guide.
    • The Topic Index duplicates the nav and links lock-options.md, which is not in the nav.
    • 9.7 dropped the Compose tutorial and lock-options.
    • The 8.0 backup-overview page is orphaned.
    • The Galera section sits inside the generic restore page.
    • Two overlapping "files" pages exist (see D56).
  • Fix: follow : add a "Restore" group that includes Verify, a method chooser, and a Troubleshooting group.

Found in a hands-on docs audit run with Claude Code.

Lingua principale
HTML
Stelle
20
Fork
40
Merge medio
17h 14m
PR unite (30g)
11

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di percona/pxb-docs

Tutte le issue di percona/pxb-docs

Issue simili

Altre issue su Databases

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.