[rasika-chivate]

Replaces PR #88 using the branch PCSM-311-PCSM-382-docs. The documentation content is identical to #88's latest commit. PR #87 retains its pre-splitting documentation unchanged. This branch includes both features, while the diff against #87 contains only target write concern changes.

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 original write concern commit passed the GitHub Vale check in PCSM-311: Document target write concern in PCSM 1.1.0 #88. The combined documentation build passed after stacking the branches.

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's review of the original write concern changes in PR #88 reported 0 open findings. Copilot balanced review requested on this replacement PR; review is pending.

[Copilot]

🟢 Approval recommended

The documentation is consistent across all configuration surfaces, and the new internal links resolve correctly.

0 open findings

What changed in this PR

Documents configurable target write concern for PCSM 1.1.0, including configuration methods, persistence, and rollback risks.

Changes:

• Documents CLI, API, and environment-variable configuration.
• Defines supported values, defaults, and recovery behavior.
• Adds operational and HA safety guidance.

File	Description
docs/​install/​usage.md	Adds configuration examples and rollback guidance.
docs/​pcsm-commands.md	Documents the new CLI flag.
docs/​install/​parameters.md	Documents the environment variable.
docs/​api.md	Documents the /start request field.
docs/​high-availability.md	Explains HA recovery implications.

🧠 Review effort: Balanced

---

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

[Copilot]

🟡 Changes recommended

The write-concern explanation incorrectly implies that sharded targets have one cluster-wide primary.

1 open finding

• Clarify w:1 behavior for sharded targets · New

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

The usage guide incorrectly implies that the server has no write concern option despite documenting the /start API option.

1 open finding

• Clarify absence of startup write concern option · New

1 resolved since last review

• Clarify w:1 behavior for sharded targets

🧠 Review effort: Balanced

[Copilot]

🟢 Approval recommended

The five-file documentation update is consistent, complete, and contains no identified blocking issues.

0 open findings

1 resolved since last review

• Clarify absence of startup write concern option

🧠 Review effort: Balanced

[rasika-chivate]

Addressed all five manual review comments in separate commits for PCSM 1.1.0.

Review comment	Change	Commit
4232469904	Updated docs/faq.md under What database read and write concerns are used? to explain the default and configurable data write concern, retain majority for checkpoints/HA/catalog operations, remove the inaccurate explicit j: true claim, and link the usage guidance.	cc63485
4234096698	Removed only the sentence introducing the hidden server --start flag from Configure target write concern.	bb96854
4234130048	Moved oplog monitoring out of the below-majority checklist, stated that it applies with any write concern, and linked the existing oplog sizing section.	cb172e3
4234158066	Restored $ prompts in all three configuration examples to match data-prompt="$" and surrounding examples.	30a4afe
4234328815	Restored backticks, the supported 1–2147483647 range, separate server-process sentence, and consistent version 1.1.0 wording for PCSM_TARGET_WRITE_CONCERN.	91adcda

Validation: MkDocs build, git diff --check, and rendered TOC, macros, command prompts, table formatting, and internal links/anchors passed for all three changed pages. Git metadata plugins were disabled for the local build. Verified that the committed GitHub files match the validated content. The five-commit diff changes only docs/faq.md, docs/install/usage.md, and docs/install/parameters.md (10 insertions, 10 deletions).

The existing about-docs.md link to missing reference/contributing.md was deliberately left alone. Local Vale is unavailable. No GitHub checks ran on the new head; the Vale workflow is configured only for PRs targeting main, whereas this PR still targets PCSM-382-skip-presplit-docs.

PR #87's branch and pre-splitting documentation remain untouched. Both features remain present in this combined branch. No manual feedback remains unresolved. Existing Copilot fixes were preserved; no new Copilot review was requested as part of this manual-comment pass.