[rasika-chivate]

Superseded by draft PR #89, which uses PCSM-311-PCSM-382-docs and targets PR #87's branch. All documentation content is preserved in the replacement. This PR's description, commits, and review remain available for reference.

PCSM 1.1.0 lets users choose the write concern for target data writes during the initial clone and ongoing replication. This documents the three configuration methods, the default and supported values, and the recovery tradeoff when using a lower write concern. Checkpoints, HA state, and catalog changes continue to use majority.

Sources: PCSM-311, developer documentation notes, merged implementation PR #284, and its README.

The documentation release 1.1.0 comes from the ticket's Fix versions field. Jira marks that release as unreleased; this PR prepares documentation for it.

This PR depends on PR #87 and targets PCSM-382-skip-presplit-docs. Merge #87 first, then retarget this PR to main. The branch includes #87's changes, and the diff against that base contains only the target write concern documentation.

Placement and changed files

• docs/install/usage.md: adds Start the replication > Configure target write concern, including CLI, HTTP API, and environment-variable examples, rollback warning, run persistence, and operational cross-references.
• docs/pcsm-commands.md: adds --target-write-concern to the start flags.
• docs/install/parameters.md: adds PCSM_TARGET_WRITE_CONCERN and makes clear that only pcsm start consumes it.
• docs/api.md: adds the string-valued targetWriteConcern field to POST /start.
• docs/high-availability.md: links the retained run setting and rollback risk from Checkpoint recovery.

The existing pages are already in mkdocs-base.yml. The new usage subsection appears in the rendered page TOC; no navigation file change is needed. Release notes are maintained separately in PR #85.

Validation

• Reviewed the complete five-file diff against PCSM-382-skip-presplit-docs (07daa53). Rebuilt the combined documentation successfully after stacking the branches.
• MkDocs build passed using the repository configuration and available documentation dependencies. Git revision-date and git-committers plugins were disabled for local validation.
• Verified the rendered page TOC, version admonition, rollback warning, three example tabs, the API JSON string type, and every new internal link and anchor.
• git diff --check passed.
• Existing warning: docs/about-docs.md links to missing reference/contributing.md; left unchanged.
• Read the Percona Style Guide's voice, callout, structure, and link guidance. Vale is unavailable locally; the repository's GitHub Vale check passed on this PR.

Claim-to-source map

Documentation claim	Source and locator
Release target is 1.1.0	PCSM-311, Fix versions
Reason to choose a lower concern: target secondaries can stall data writes	Ticket Problem; PR #284 Problem; README Target data write concern
CLI flag, environment variable, string API field, flag precedence, default majority, server ignores env variable and auto-start defaults	Developer comment 479415 Docs Notes; PR #284 main.go (newStartCmd, resolveStartOptions, startRequest), config/config.go (bindEnvVars), cli_write_concern_test.go (TestStartTargetWriteConcernPrecedence)
Accepted values: majority or decimal 1 through 2147483647; zero, negative, overflow and named concerns rejected	PR #284 config/write_concern.go (ParseTargetWriteConcern), config/write_concern_test.go, CLI/API validation tests; developer comment Docs Notes
Selected concern affects clone and replication data writes; checkpoints, HA state and catalog DDL remain majority	Ticket Acceptance criteria; PR #284 clone, replication bulk writer, catalog and checkpoint changes; README Target data write concern
Value retained during recovery/HA takeover; resume cannot change it; new run required	Developer comment Docs Notes; README; PR #284 pcsm/pcsm.go (Checkpoint, Recover, Start)
Below-majority write acknowledgment can roll back after target primary failure/stepdown; majority checkpoints do not protect prior data writes; controlled migration, source retained and target verified	README Target data write concern; developer comment Docs Notes; MongoDB 8.0 Write concern, w option
Meaning of numeric write concern and primary-only acknowledgment for 1	MongoDB 8.0 Write concern, w option
Effective write concern is recorded for clone and replication	Developer comment QA Notes; PR #284 pcsm/clone/clone.go (NewClone), pcsm/repl/repl.go (NewRepl)
Source oplog window should be monitored and extended when the target slows down	Developer comment Docs Notes; existing docs/oplog-sizing.md
New start recreates selected target collections	Existing docs/install/usage.md, Target collections are overwritten on start warning

No claims of adjustable write concern on resume are included. PCSM-395 tracks that separate, open improvement.

[Copilot]

🟢 Approval recommended

The documentation is consistent across all configuration surfaces and clearly describes operational risks.

0 open findings

What changed in this PR

Documents configurable target write concern support introduced in PCSM 1.1.0.

Changes:

• Documents CLI, API, and environment-variable configuration.
• Explains defaults, validation, persistence, and rollback risks.
• Connects the setting to HA recovery and operational guidance.

File	Description
docs/​install/​usage.md	Adds comprehensive configuration and safety guidance.
docs/​pcsm-commands.md	Documents the new start flag.
docs/​install/​parameters.md	Documents the environment variable.
docs/​api.md	Documents the /start request field.
docs/​high-availability.md	Explains persistence and rollback implications during takeover.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.