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

[Docs audit] Concept pages contain factual errors (MariaDB, incremental definition, implementation details, glossary, FAQ, peripheral pages)

Aperta
  • Qualcosa non va?
#526 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
1-2 giorni
Idoneità per principianti
45/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
mariadb
Ambito
databases, documentation

Direzione di ricerca

Start with docs/backup-overview.md line 3 on the 8.4 branch, then check the same claims in differences-logical-backup, features, about-xtrabackup, xtrabackup-implementation-details, glossary and faq, and compare the incremental-backup wording with backup-strategy.md, which the issue says is already correct. Peripheral fixes are in verify-backup.md and the update-curl-utility and toolkit-version-check pages. Done means each listed wrong statement is corrected on the affected branches (8.0, 8.4, 9.7) and the replacement texts F20, F21 and F24 are applied, though those IDs are not in this payload.

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: D60 (Medium), D51 (Low), D52 (Low)

D60. Concept pages contain factual errors: MariaDB, incremental and partial definitions, "no load", implementation details, glossary, FAQ

  • Severity: Medium
  • Series: 8.4, 9.7 (backup-overview also in 8.0)
  • Pages:
    • 8.4/backup-overview (:3-15)
    • differences-logical-backup (:8,19,27)
    • features (:15)
    • about-xtrabackup (:7-19)
    • xtrabackup-implementation-details (:8-13,39-44)
    • glossary
    • faq (:6-68)
  • What happened:
    • Wrong scope and mechanics:
      • PXB does not support MariaDB.
      • It copies only the current binlog fragment, not "the binary log files".
    • Wrong definitions:
      • An incremental backup copies pages changed since the previous backup, full or incremental. A verified chain shows inc2's from_lsn equals inc1's to_lsn, and backup-strategy.md already says this correctly.
      • A partial backup is a set of selected tables or databases, not "files changed in a folder".
      • Logical dumps can include users.
    • Overstated claims:
      • "No load": strace shows 10 MiB reads.
      • "Non-blocking": non-InnoDB writes are blocked on PS.
      • "Verify backup automatically": no such feature exists.
    • Implementation details are wrong:
      • PXB needs read access only; it ran as a group-read OS user.
      • Reads are --read-buffer-size, 10 MiB by default and configurable, not "1 MB non-configurable".
      • Redo is read in 64 KiB chunks.
      • innodb_log_block_size does not exist.
    • Glossary errors:
      • .frm, .par, .TRG, .TRN and .opt do not exist in 8.x.
      • The data dictionary lives in mysql.ibd.
      • ibdata1 is 12 MB, not 10 MB.
      • The variable is innodb_log_group_home_dir, not innodb_log_group_home.
    • FAQ errors:
      • The "1048576 hard-coded" claim is wrong; the limit is fs.nr_open, 1073741816 on Rocky 10.
      • The ZRM link returns 403.
      • The optimized-DDL error text differs from 8.4's.
  • Fix: apply the replacement texts in F20, F21, F24 and . For example, backup-overview line 3 becomes: "...physical backups of MySQL and Percona Server for MySQL (MariaDB is not supported; use mariabackup). It copies InnoDB data files and the redo log generated during the copy, plus non-InnoDB files and the current binary log fragment."

D51. Peripheral pages are outdated: verify-backup, update-curl-utility, toolkit-version-check

  • Severity: Low
  • Series: 8.4 (verify-backup in all series)
  • What happened:
    • verify-backup (8.4:verify-backup.md:4,11-13,28,33,80):
      • percona.com/doc links soft-404 to the docs home page;
      • GRANT ... IDENTIFIED BY fails on 8.x;
      • the replication guide is not linked.
    • update-curl-utility:
      • it checks the curl CLI instead of the library xbcloud loads;
      • apt install --reinstall cannot downgrade;
      • the curl 7.88.1 sample with "Metalink" is fabricated (7.88.1 was released on 2023-02-20 and has no Metalink);
      • it gives Debian 12 instructions only;
      • the page title and nav label disagree.
    • toolkit-version-check:
      • PXB 8.4 performs no version check (strace shows only connects to the local socket);
      • --no-version-check is a deprecated no-op.
      • PXB 8.0 does run the check, per .
  • Fix:
    • verify-backup: use https://docs.percona.com/percona-toolkit/pt-table-checksum.html and CREATE USER.
    • update-curl-utility: check with ldd $(which xbcloud) | grep libcurl and dpkg -l 'libcurl4*' / rpm -q libcurl, give an explicit-version downgrade, and add a per-distribution table.
    • toolkit-version-check: "PXB 8.4 does not perform a version check".

D52. Mixed slave/master and replica/source terminology

  • Severity: Low
  • Series: 8.0, 8.4, 9.7
  • What happened: 8.4 and 9.7 use --slave-info, --safe-slave-backup and xtrabackup_slave_info next to "replica" prose. 8.0 uses CHANGE MASTER, START SLAVE and SHOW SLAVE STATUS.
  • Fix: add a Terminology note mapping slave to replica and master to source, stating which option names each series accepts.

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.