# 7. Contributing

How to fix or extend this wiki.

## Quick fix (a typo, a sentence)

1. Edit the relevant `.md` file under `docs/`.
2. Run `mkdocs build` to regenerate the static site under `site/`, or
   `../.venv/bin/mkdocs build` to regenerate the static site under
   `../site/en/`, or `../.venv/bin/mkdocs serve` to preview live.
3. Commit when satisfied.

The wiki lives on this machine — there is no remote, no CI, no Pages.
Anyone reading the wiki opens `site/index.html` locally or runs
`mkdocs serve` themselves.

## Local dev (preview while editing)

```bash
cd xly-wiki/en
../.venv/bin/mkdocs serve         # http://127.0.0.1:8000 with live reload
```

## Regenerate the auto-catalog

```bash
python scripts/gen_catalog.py     # queries live DB via ~/.my.cnf, writes docs/auto-catalog/**
```

The script connects directly to the live MySQL using the `[client]`
section of `~/.my.cnf`. Override either side with environment variables
when needed:

```bash
DB_DEFAULTS_FILE=/path/to/other.cnf python scripts/gen_catalog.py
DB_NAME=xlyweberp_some_other      python scripts/gen_catalog.py
```

The generator wipes and rewrites every file under `docs/auto-catalog/{tables,views,procedures,functions}/`
on each run. Hand-edits in those directories will be lost.

## Pre-commit hook (optional but recommended for local edits)

Install once:

```bash
ln -s ../../scripts/precommit.sh .git/hooks/pre-commit
chmod +x scripts/precommit.sh
```

The hook runs `mkdocs build --strict` on every commit so broken cross-refs are
caught before they land in a commit.

## Style

- **Markdown source is the source of truth.** Static HTML in `site/` is
  generated; never hand-edit it.
- **English prose. Chinese terms preserved untranslated** in body text. The
  [Glossary](glossary.md) is the one place translations live.
- **Slices are the only place narrative belongs.** Concepts and reference
  pages stay short — if a concept page grows past ~300 words, that content
  probably wants to be a slice instead.
- **Auto-catalog pages are not hand-edited.** Cross-link *into* them from
  hand-written content; never the other way.
- **Cross-link liberally.** Every framework-table mention in a slice should
  link to its auto-catalog page. Every concept term should link to its
  Concepts page on first mention.

## Adding a new slice

1. Create `docs/slices/NN-<name>.md`.
2. Add it to `mkdocs.yml` nav.
3. Document the slice end-to-end (one UI action, all layers).
4. Cross-link every term to Concepts; every table/proc to Auto-Catalog.
5. Update the [Slices index](slices/index.md) table.

## Adding a new concept

Only add a concept page when at least one slice introduces it. Concepts that
nothing references are dead weight.