Skip to content

docs(contribution): add a local build and test workflow page - #389

Open
qwer381 wants to merge 1 commit into
IvorySQL:masterfrom
qwer381:docs/developer-workflow
Open

qwer381 wants to merge 1 commit into
IvorySQL:masterfrom
qwer381:docs/developer-workflow

Conversation

@qwer381

@qwer381 qwer381 commented Nov 11, 2026 •

Copy link
Copy Markdown

Closes #385

What this changes

New page CN|EN/modules/ROOT/pages/master/contribution/developer_workflow.adoc (290 lines each) plus one line in each nav.adoc, inserted right after the contribution guide entry:

  • CN nav.adoc: after ** xref:master/contribution/contribution_guide.adoc[贡献指南]
  • EN nav.adoc: after ** xref:master/contribution/contribution_guide.adoc[Contribution Guide]

The page covers the path from a clean checkout to an accepted patch:

  1. Prerequisites — build dependencies, the extra tools the page assumes, and why tests must not run as root (initdb: error: cannot be run as root).
  2. Building from source — configure, the --with-uuid=bsd|e2fs|ossp requirement and what happens when it is omitted, make, make install, and --enable-tap-tests.
  3. Initializing a dual-mode instance — initdb -m oracle vs -m pg, the relationship between Oracle mode and the uuid-ossp extension, and what initdb -L does and does not change (-L overrides the input files initdb reads; CREATE EXTENSION during bootstrap still resolves against the compiled-in SHAREDIR, so -L cannot be used to point at a temporary extension directory).
  4. Three test tiers — TAP (make -C <dir> check), core regression, and the Oracle-compatible regression target, with the note that the shared TAP template initializes in pg mode, so Oracle-mode coverage has to bring its own instance.
  5. Sending a patch — commit message style, the AI-assistance trailer the repository asks for, git format-patch / git send-email, and the CLA.
  6. Common failures — a short table mapping symptoms to causes (missing --with-uuid, no TAP prerequisites, running as root, Oracle-mode tests failing because the extension is absent).

How it was verified

The TAP transcript quoted in the page is a real run on IvorySQL 5.6:

t/001_initdb.pl ............. ok
t/002_gb18030.pl ............ ok
t/003_uuid_ossp_missing.pl .. ok
Files=3, Tests=86, 19 wallclock secs
Result: PASS

The configure excerpts come from configure --help of the same tree, and the #error path was reproduced by building with --with-uuid omitted.

Two tiers are not run in this batch, and the page says so explicitly instead of pasting output: core regression (make check) and the Oracle-compatible regression target. They are documented as commands with a note that the output is environment-dependent.

Rendering: both languages convert with asciidoctor.js 4.2.1, zero warnings, identical heading structure (= ×1, == ×8, === ×16, ==== ×1).

Checklist

  • CLA signed and on file (individual CLA emailed to cla@ivorysql.org on 2026-11-10)
  • nav.adoc change is a single inserted line per language, no reordering
  • Bilingual: CN and EN pages are line-for-line symmetric

developer_guide.adoc is SQL and PL reference material, and the contribution
guide covers the CLA, commit style and how to send a patch, but nothing
explains how to build the tree or run the test suites. A new contributor
has to reverse-engineer that from configure --help and the CI workflows.

Add master/contribution/developer_workflow.adoc in CN and EN, plus one
navigation entry per language, covering:

- prerequisites, including why the tests must not run as root (initdb
  refuses to run as root, which is the first thing that breaks inside a
  container);
- configure, the --with-uuid=bsd|e2fs|ossp requirement and what happens
  when it is omitted (configure silently sets with_uuid=no and the build
  stops at contrib/uuid-ossp with an #error), and --enable-tap-tests;
- initializing an instance in both compatible modes, and what initdb -L
  does and does not change: it overrides the input files initdb reads, but
  CREATE EXTENSION during bootstrap still resolves against the compiled-in
  SHAREDIR;
- three test tiers (TAP, core regression, Oracle-compatible regression),
  noting that the shared TAP template initializes in pg mode, so Oracle
  mode coverage has to bring its own instance;
- sending a patch: commit message style, the AI-assistance trailer, and
  the CLA.

The TAP transcript quoted on the page is a real 5.6 run; the two other
tiers are documented as commands only, because they were not measured when
the page was written.
@github-actions
github-actions Bot temporarily deployed to pull request November 11, 2026 16:46 Inactive
@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

@qwer381

qwer381 commented Nov 12, 2026 •

Copy link
Copy Markdown
Author

CI is green and the rendered result has been verified on the deploy preview.

  • build-and-deploy: success (job completed), mergeStateStatus=clean, base master @ 7d4ad9d.
  • Preview check (both languages, HTTP 200): /cn/ivorysql-doc/master/contribution/developer_workflow.html and /en/ivorysql-doc/master/contribution/developer_workflow.html.
  • Rendered content matches the patch: the new page (build from source, init in both modes, three tiers of local testing, submitting a patch); no {asterisk} leftovers and no nested-markup artifacts.
  • nav position was verified against the live sidebar order, not just the diff.

Nothing else is pending on my side -- happy to adjust wording or split anything if you prefer a different shape for this section.

@qwer381
qwer381 force-pushed the docs/developer-workflow branch from d91289d to cb083e0 Compare November 13, 2026 05:53
@github-actions
github-actions Bot temporarily deployed to pull request November 13, 2026 05:56 Inactive
@github-actions

Copy link
Copy Markdown

🚀 IvorySQL-Docs Preview Ready

This branch was previously deployed

1 inactive deployment
pull request — cb083e0e Deployed Nov 13, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants