Skip to content

Correct and clean up developer setup documentation - #1124

Open
papeh wants to merge 6 commits into
mainfrom
fix/documentation
Open

Correct and clean up developer setup documentation#1124
papeh wants to merge 6 commits into
mainfrom
fix/documentation

Conversation

@papeh

@papeh papeh commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Documentation was out of sync with reality (both ahead and behind). Correct documentation and remove redundant documentation.

CI-ready checklist

(https://github.com/sillsdev/FieldWorks/blob/main/.github/commit-guidelines.md).

  • As much as possible, the change is unit tested.
  • Builds & tests pass locally (or I've run the CI-style build via build.ps1, test.ps1, or MSBuild).
  • If this is core-developer AI-assisted work, I followed Docs/workflows/ai-pr-workflow.md and ran pr-preflight or the equivalent branch-readiness review before requesting review.
  • For any Src/** folders touched, corresponding AGENTS.md files are updated or explicitly confirmed still accurate.
  • I have considered all comments from an AI code reviewer (such as Devin)
Reading this a year from now -- start here

This PR is a documentation correction and de-duplication pass across Docs/CONTRIBUTING.md and Docs/core-developer-setup.md. There's no code behind it and no research artifact was produced or deleted — the reasoning below is all there is.

Decisions, and why
  • CONTRIBUTING.md is the source of truth for any contributor. Where the same instruction (e.g. git rename-limit config, the Visual-Studio-vs-VS-Code switching guidance, the AI-Assisted PR Workflow pointer) applied equally to core and non-core developers, it was kept once in CONTRIBUTING.md and removed from core-developer-setup.md, with a cross-reference left behind instead of silently dropping it.
  • core-developer-setup.md keeps only what's actually core-developer-specific: write access / SSH key setup, git identity configuration, release branch tracking, branch naming conventions, and release-manager escalation contacts. None of that is meaningful for a non-core contributor, so it wasn't a duplication candidate.
Evidence
  • git diff --name-status origin/main...HEAD -- '*.md' shows exactly the two files touched: Docs/CONTRIBUTING.md, Docs/core-developer-setup.md.
  • Every concrete path/script named in the edited sections was checked against the tree and resolves: Setup-Developer-Machine.ps1, Build/Agent/Setup-DefenderExclusions.ps1, Build/Agent/Verify-FwDependencies.ps1, Build/Agent/Setup-InstallerBuild.ps1, Docs/workflows/ai-pr-workflow.md, Docs/visual-studio-setup.md, Docs/installer-build-guide.md, Docs/vscode-stability-profile.md, .github/instructions/build.instructions.md, .github/commit-guidelines.md, Docs/workflows/pull-request-workflow.md, Docs/workflows/release-process.md, DistFiles/Graphite/pl/piglatin.ttf, build.ps1, test.ps1.
  • Removed rename-limit git config block was confirmed present verbatim in CONTRIBUTING.md's "Git Configuration Reference" section before deleting it from core-developer-setup.md (it had been stated three times across the two files).
Reviewable

This change is Reviewable

Co-authored-by: Claude Sonnet 5 noreply@anthropic.com

* Fix instructions for reporting bugs
* Consolidate redundant sections in CONTRIBUTING and core-developer-setup
* Suggest a private email address for git config
* Clarify requirements for installer, FlexBridge, and Paratext work

TODO: figure out WiX requirements
* Move git config instructions to CONTRIBUTING.md
@papeh papeh changed the title Correct and de-duplicate developer setup documentation Correct and clean up developer setup documentation Sep 4, 2026
@github-actions

github-actions Bot commented Sep 4, 2026

Copy link
Copy Markdown

NUnit Tests

    1 files  ±0      1 suites  ±0   12m 38s ⏱️ +59s
6 011 tests ±0  5 930 ✅ ±0  81 💤 ±0  0 ❌ ±0 
6 020 runs  ±0  5 939 ✅ ±0  81 💤 ±0  0 ❌ ±0 

Results for commit 01a1132. ± Comparison against base commit 1ab408b.

♻️ This comment has been updated with latest results.

@codecov-commenter

codecov-commenter commented Sep 4, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 38.58%. Comparing base (1ab408b) to head (01a1132).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1124   +/-   ##
=======================================
  Coverage   38.57%   38.58%           
=======================================
  Files        1514     1514           
  Lines      351014   351014           
  Branches    40355    40355           
=======================================
+ Hits       135418   135432   +14     
+ Misses     186380   186368   -12     
+ Partials    29216    29214    -2     

see 3 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

papeh and others added 2 commits September 4, 2026 11:50
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
@papeh
papeh marked this pull request as ready for review September 4, 2026 18:44
@papeh
papeh marked this pull request as draft September 4, 2026 19:20
@papeh
papeh marked this pull request as ready for review September 4, 2026 19:35
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