Kinneyzhang 83352c4571 feat!: add source-clean live buffer layout

Replace the physical ekp-region renderer with ekp-buffer text-property projection backed by shared semantic layout plans and stable live-edit transactions.

Optimize the C-backed resize hot path, and add deterministic performance, ERT, GUI, fuzz, release, and documentation coverage for task017 through task032.

BREAKING CHANGE: require ekp-buffer instead of ekp-region and rename module-owned ekp-region-* settings to ekp-buffer-*.

2026-07-30 01:07:25 +08:00

2.6 KiB

Raw Blame History

Contributing to emacs-kp

Thanks for your interest. This document covers the essentials for making a change that will pass review and CI.

Development setup

EMACS=emacs   # or /path/to/Emacs

# Byte-compile with warnings as errors (CI does this)
$EMACS -Q --batch -L . \
  --eval '(setq byte-compile-error-on-warn t)' \
  -f batch-byte-compile ekp.el ekp-utils.el ekp-hyphen.el ekp-buffer.el

# Run the ERT suite (C-module tests auto-skip if not built)
tests/run-tests.sh $EMACS

# Build the C module (required for the parity tests and fuzz)
make -C ekp_c PROFILE=portable

# Property fuzz: 300 random cases, asserts C and Elisp agree byte-for-byte
$EMACS -Q --batch -L . -l tests/ekp-fuzz.el

# Check release/CI/version invariants
tests/check-release.sh

# Check dictionary inventory and pinned upstream bytes
tests/check-dictionaries.sh
dictionaries/update.sh check

Ground rules

The two engines must produce byte-identical output. Any change to the demerits or line-metric formulas must touch both ekp--dp-run-1d (Elisp) and dp_process_position (ekp_c/ekp_kp.c), and the fuzz suite must stay at 300/300.
The two renderers have different rights. The string renderer's physical marker vocabulary (ekp-glue, ekp-soft-break, ekp-soft-hyphen, ekp-hidden) stays lossless and compatible. The buffer renderer must create no overlay or source character and may use only EKP-owned text properties on existing characters.
Any C-module API change bumps EKP_VERSION_MINOR and the matching ekp-c-module-required-version, and rebuilds the module.
New behavior needs an ERT test. Buffer-level behavior (save, isearch, undo, kill/yank, mode interactions) goes in tests/ekp-buffer-tests.el.

Style

lexical-binding: t everywhere; keep byte-compilation warning-free.
checkdoc clean (CI enforces it): imperative docstring first lines, arguments mentioned in uppercase, two spaces after a sentence.
package-lint clean: the ekp- / ekp-buffer- namespaces, proper autoload cookies on interactive entry points.
Match the surrounding code; keep comments about why, not what.

Commits

Conventional Commits (feat:, fix:, perf:, refactor!:, docs:, test:, chore:). Explain the reasoning in the body, not just the change.

Releases

Follow Docs/RELEASING.md. In particular, action dependencies stay pinned to full commit SHAs, released artifacts are immutable, and every artifact gets a SHA-256 checksum.

License

By contributing you agree that your contributions are licensed under GPL-3.0-or-later, matching the project (see COPYING).

2.6 KiB Raw Blame History