diff --git a/Docs/CONTRIBUTING.md b/Docs/CONTRIBUTING.md index 497f072a34..9c8369cadf 100644 --- a/Docs/CONTRIBUTING.md +++ b/Docs/CONTRIBUTING.md @@ -7,8 +7,11 @@ Thank you for your interest in contributing to FieldWorks (FLEx)! There are several ways you can contribute to the development of FieldWorks: - **Contributing code** - Fix bugs, add features, improve documentation -- **Testing alpha and beta versions** - Help us find and report issues -- **Reporting issues** - File bugs on [GitHub Issues](https://github.com/sillsdev/FieldWorks/issues) +- **Testing alpha and beta versions** - Help us find and report issues ([download](https://software.sil.org/fieldworks/download/) from our website or choose Tools > Options > Updates and automatically download Alpha or Beta updates) +- **Reporting bugs** - We plan to enable [GitHub Issues](https://github.com/sillsdev/FieldWorks/issues) in the near future. Until then, you can + - Choose Help > Report a Problem... from within FieldWorks + - Fill out the [contact form](https://software.sil.org/fieldworks/about/contact/) at our website + - Create an account on [Jira](https://jira.sil.org/issues/?jql=project%20%3D%20LT) ## Getting Started @@ -35,15 +38,10 @@ Required workloads: - .NET desktop development - Desktop development with C++ (including ATL/MFC) -#### WiX Toolset (v6 via NuGet restore) (for installer building) +Optional Visual Studio extension: +- **ReSharper** (if you have a license) for advanced refactoring/navigation -Installer builds use SDK-style `.wixproj` projects and restore WiX v6 tooling via NuGet during the build. - -```powershell -.\Setup-Developer-Machine.ps1 -``` - -See [Installer Build Guide](installer-build-guide.md) for building installers locally. +Visual Studio Code is an option for some development if you prefer it to Visual Studio. See [VS Code Stability Profile](vscode-stability-profile.md). #### Windows Defender Exclusions (Recommended) @@ -73,12 +71,24 @@ git clone git@github.com:sillsdev/FieldWorks.git cd FieldWorks ``` -#### Optional: Clone FwLocalizations (for translation work) +#### Run the setup script -If you're working on translations: +```powershell +.\Setup-Developer-Machine.ps1 + +# Option: set up with installer helper repositories (Helps, Localizations, etc.) +.\Setup-Developer-Machine.ps1 -InstallerDeps +``` + +See [Installer Build Guide](installer-build-guide.md) for building installers locally. + +#### Optional: Clone FwLocalizations and LibLCM (for translation work) + +If you're working on translations, and you didn't run `.\Setup-Developer-Machine.ps1 -InstallerDeps`: ```powershell git clone https://github.com/sillsdev/FwLocalizations.git Localizations +git clone https://github.com/sillsdev/liblcm.git Localizations/LCMRepo ``` #### Set up fonts for Non-Roman test data @@ -96,8 +106,14 @@ $env:FEEDBACK = "off" # Set up ICU data path (required for debugging ICU-related projects) $env:ICU_DATA = "C:\path-to-repo\DistFiles\Icu70\icudt70l" -# For FlexBridge development (optional) +# For Paratext integration (optional) $env:FIELDWORKSDIR = "C:\path-to-repo\Output\Debug" + +# For FlexBridge development (optional) +$env:FLEXBRIDGEDIR = "C:\path-to-repo\Output\Debug\net462" + +# For working on translations (optional) +$env:LcmRootDir = "C:\path-to-liblcm-repo" ``` > **Tip**: Add these to your PowerShell profile or system environment variables for persistence. @@ -114,7 +130,7 @@ For more build options, see [.github/instructions/build.instructions.md](../.git On Linux or macOS, do not run `build.ps1` or `test.ps1`; those entry points intentionally fail fast with a not-supported message. -### Run tests from the command line +### 5. Run tests from the command line Use `test.ps1` for local test runs: @@ -140,31 +156,37 @@ Remove-Item Env:FW_TEST_ALLOW_ASSERT_DIALOGS Only use this opt-in for attended local debugging. CI and normal local runs should leave it unset. -### 5. VS Code and Visual Studio usage +## Git Configuration -Default recommendation: -- Use **VS Code + ReSharper extension** for everyday coding, navigation, and managed test explorer workflows. -- **C# Dev Kit is discouraged** in this workspace. -- Use repo scripts/tasks as source of truth for build/test: `./build.ps1` and `./test.ps1`. +It is helpful to increase the rename limits for Git to properly detect renames in large commits: -If you are a core developer using GitHub Copilot or Claude Code, follow [AI-Assisted PR Workflow](workflows/ai-pr-workflow.md) for the Jira-to-PR path: create a dedicated worktree, validate with repo tasks/scripts, run `pr-preflight`, and then work review comments through the repo review-response workflow. +```powershell +git config diff.renameLimit 10000 +git config merge.renameLimit 10000 +``` -Switch to **Visual Studio** (2026 or 2022) when you need: -- WinForms designer workflows -- Mixed managed/native debugging across interop boundaries -- Complex legacy .NET Framework project-system scenarios where VS Code is unreliable +### Recommended Global Settings -See [VS Code Stability Profile](vscode-stability-profile.md) for current workspace guidance. +```powershell +# Use rebase by default when pulling +git config --global pull.rebase true -#### Git Configuration Tips +# Prune deleted remote branches on fetch +git config --global fetch.prune true -It is helpful to increase the rename limits for Git to properly detect renames in large commits: +# Use diff3 conflict style for better merge conflict resolution +git config --global merge.conflictstyle diff3 -```powershell -git config diff.renameLimit 10000 -git config merge.renameLimit 10000 +# Enable helpful coloring +git config --global color.ui auto ``` +### Recommended Git GUI Tools + +- **Git GUI** (included with Git) - for commits and basic operations +- **GitKraken** or **SourceTree** - for visual branch management +- **Visual Studio** (and **VS Code**) have Git integration + ## Contributing Code ### General Guidelines @@ -200,7 +222,7 @@ People we know well might be asked to join the core development team. Core devel ## Getting Help - **Documentation**: Check the [docs/](.) folder for additional guides -- **Issues**: Search or file issues on [GitHub](https://github.com/sillsdev/FieldWorks/issues) +- **Issues**: Search or file issues on [Jira](https://jira.sil.org/issues/?jql=project%20%3D%20LT) - **Wiki**: Historical documentation at [FwDocumentation wiki](https://github.com/sillsdev/FwDocumentation/wiki) (being migrated to this repository) ## See Also diff --git a/Docs/core-developer-setup.md b/Docs/core-developer-setup.md index 9ddabb18d4..9ed801c1ab 100644 --- a/Docs/core-developer-setup.md +++ b/Docs/core-developer-setup.md @@ -6,39 +6,7 @@ This document describes additional setup steps for core FieldWorks developers. U ## Prerequisites -Complete all steps in [CONTRIBUTING.md](CONTRIBUTING.md) first: -1. Install required software (Git, Visual Studio 2026 or 2022) -2. Clone the repository -3. Verify you can build successfully - -## Required Software - -The following tools are required for FieldWorks development: - -### Visual Studio 2026 or 2022 - -FieldWorks builds with either; when both are installed the build uses the newest. -Install with these workloads: -- **.NET desktop development** -- **Desktop development with C++** (including ATL/MFC components) - -See [Visual Studio Setup](visual-studio-setup.md) for the detailed component list, or import the repo-root `.vsconfig` in the Visual Studio Installer. - -### WiX Toolset (v6 via NuGet restore) - -Installer builds use SDK-style `.wixproj` projects and restore WiX v6 tools via NuGet during the build. No separate WiX 3.x installation is required. - -```powershell -# Standard developer machine setup -.\Setup-Developer-Machine.ps1 - -# Optional: set up installer helper repositories -.\Setup-Developer-Machine.ps1 -InstallerDeps -``` - -### Environment Variables - -No WiX-specific environment variables are required for WiX v6 SDK builds. +Complete all steps in [CONTRIBUTING.md](CONTRIBUTING.md) first. ### Verification @@ -104,86 +72,45 @@ For streamlined pushing and pulling, set up an SSH key: ```powershell git config user.name "Your Name" -git config user.email "your.email@example.com" -``` - -#### Increase Rename Limits - -```powershell -git config diff.renameLimit 10000 -git config merge.renameLimit 10000 +git config user.email "your.github.id@users.noreply.github.com" ``` #### Configure Branch Tracking -Set up tracking for release branches you'll be working on: +Set up tracking for branches you'll be working on: ```powershell # Fetch all branches git fetch --all -# Track a specific release branch -git checkout release/9.3 +# Track the main branch +git checkout main ``` -### 3. Development Environment - -#### IDE Extensions - -Recommended VS Code extensions for daily development: -- **ReSharper for VS Code** (`jetbrains.resharper-code`) for C# editing, navigation, refactoring, and test explorer -- **C# Dev Kit** (`ms-dotnettools.csdevkit`) and **C#** (`ms-dotnettools.csharp`) are discouraged in this workspace -- **C/C++** (`ms-vscode.cpptools`) for native editing/debugging -- **PowerShell** (`ms-vscode.powershell`) for build/test scripts - -Use **Visual Studio** (2026 or 2022) when working on: -- WinForms designer changes -- Mixed managed/native debugging across interop boundaries -- Complex legacy .NET Framework project-system issues - -Optional Visual Studio extension: -- **ReSharper** (if you have a license) for advanced refactoring/navigation - -#### Git GUI Tools - -Recommended Git tools: -- **Git GUI** (included with Git) - For commits and basic operations -- **GitKraken** or **SourceTree** - For visual branch management -- **VS Code** - Has excellent Git integration - ## AI-Assisted PR Workflow For core developers, the canonical AI-assisted path is now [AI-Assisted PR Workflow](workflows/ai-pr-workflow.md). -Use that guide when you want the full FieldWorks workflow from Jira through merge-ready review: - -1. Pull the Jira ticket through approved Atlassian tooling. -2. Create a dedicated branch worktree with the repo task. -3. Build and test with `./build.ps1`, `./test.ps1`, or the matching VS Code tasks. -4. Run `pr-preflight` before opening or updating the PR. -5. Use the review-response workflow for Copilot and human comments. +## Working with Branches -If you use Claude Code, create the worktree with the repo task first, then launch Claude inside that worktree. - -### 4. Working with Branches - -#### Branch Naming Conventions +### Branch Naming Conventions - `feature/` - New features - `bugfix/-` - Bug fixes - `hotfix/` - Emergency fixes for released versions - `release/` - Release preparation branches +- `main` - Main development on the current or upcoming release -#### Creating Feature Branches +### Creating Feature Branches ```powershell # Create a new feature branch from the default branch -git checkout release/9.3 +git checkout main git pull git checkout -b feature/my-feature-name ``` -#### Submitting Changes +### Submitting Changes 1. Push your branch to origin: ```powershell @@ -198,41 +125,13 @@ git checkout -b feature/my-feature-name See [AI-Assisted PR Workflow](workflows/ai-pr-workflow.md) for the canonical core-developer workflow, and [Pull Request Workflow](workflows/pull-request-workflow.md) for the generic GitHub PR mechanics. -### 5. Release Management +## Release Management -If you are a release manager, additional setup may be required. Contact Jason Naylor for: +If you are a release manager, additional setup may be required. Contact the team lead for: - Access to release automation scripts - Build server access - Installer signing certificates -## Git Configuration Reference - -### Recommended Global Settings - -```powershell -# Use rebase by default when pulling -git config --global pull.rebase true - -# Prune deleted remote branches on fetch -git config --global fetch.prune true - -# Use diff3 conflict style for better merge conflict resolution -git config --global merge.conflictstyle diff3 - -# Enable helpful coloring -git config --global color.ui auto -``` - -### Repository-Specific Settings - -These are set in the FieldWorks repository: - -```powershell -# Increase rename detection limits -git config diff.renameLimit 10000 -git config merge.renameLimit 10000 -``` - ## Troubleshooting ### Permission Denied on Push diff --git a/Docs/installer-build-guide.md b/Docs/installer-build-guide.md index 693e88f0bc..33d7a1f127 100644 --- a/Docs/installer-build-guide.md +++ b/Docs/installer-build-guide.md @@ -21,7 +21,7 @@ Use the installer setup script to validate your environment: ### Required Software 1. **Visual Studio 2026 or 2022** with Desktop workloads (C++ and .NET). Official installers are produced from Visual Studio 2022 (v143) builds; a v145 build gets a warning because the bundled VC++ redistributables predate that toolset. -2. **WiX Toolset v3.x** for the legacy WiX 3 build (default), plus the **Visual Studio WiX Toolset v3 extension** so `Wix.CA.targets` is available under MSBuild +2. **WiX Toolset v3.14** for the legacy WiX 3 build (default), plus the **Visual Studio WiX Toolset v3 extension** so `Wix.CA.targets` is available under MSBuild 3. **WiX Toolset v6** via `WixToolset.Sdk` for the opt-in WiX 6 build (restored via NuGet as part of the build) 4. **MSBuild** (included with Visual Studio) 5. **.NET Framework 4.8 SDK** (included with Visual Studio) @@ -58,14 +58,7 @@ git clone https://github.com/sillsdev/liblcm.git Localizations/LCMRepo ### Full Build (Recommended) ```powershell -# Open VS Developer Command Prompt (x64) or run: -# & "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\Launch-VsDevShell.ps1" -Arch amd64 - -# Restore packages -msbuild Build/InstallerBuild.proj /t:RestorePackages /p:Configuration=Debug /p:Platform=x64 - -# Build base installer (x64 only) -msbuild Build/InstallerBuild.proj /t:BuildInstaller /p:Configuration=Release /p:Platform=x64 /p:config=release /m /v:n +.\build.ps1 -BuildInstaller -Configuration Release ``` ### Output Location @@ -88,11 +81,7 @@ These can be downloaded from GitHub Releases (e.g., `build-1188`). ### Build Command ```powershell -# Restore packages -msbuild Build/InstallerBuild.proj /t:RestorePackages /p:Configuration=Debug /p:Platform=x64 - -# Build patch installer (x64 only) -msbuild Build/InstallerBuild.proj /t:BuildPatchInstaller /p:Configuration=Release /p:Platform=x64 /p:config=release /m /v:n +.\build.ps1 -BuildPatch -Configuration Release ``` ### Output Location @@ -147,10 +136,6 @@ The automated build process is defined in two GitHub Actions workflows: - `base_build_number`: Numeric base build number - `make_release`: Whether to upload to S3 (default: true) -### WiX Version - -Workflows should use **WiX Toolset v6** via `WixToolset.Sdk` restored from NuGet. - ## Troubleshooting ### WiX tool resolution failures diff --git a/Docs/visual-studio-setup.md b/Docs/visual-studio-setup.md index 84adf4dadf..c3d9f9e3d8 100644 --- a/Docs/visual-studio-setup.md +++ b/Docs/visual-studio-setup.md @@ -102,7 +102,7 @@ Then use Visual Studio for editing and debugging. ## Debugging FieldWorks -1. Set **FieldWorks** (or the specific project you're working on) as the **Startup Project** +1. Ensure **FieldWorks** is the **Startup Project** 2. Ensure the configuration is **Debug** and platform is **x64** 3. Press **F5** to start debugging diff --git a/Docs/vscode-stability-profile.md b/Docs/vscode-stability-profile.md index d5724eefee..4b5900f326 100644 --- a/Docs/vscode-stability-profile.md +++ b/Docs/vscode-stability-profile.md @@ -1,13 +1,15 @@ # VS Code Stability Profile (FieldWorks) This repository is a mixed native + managed solution (C++ + .NET Framework `net48`) with traversal orchestration in `FieldWorks.proj`. +See [Contributing](CONTRIBUTING.md) for the recommended Visual Studio. -## Supported inner-loop in VS Code +## Recommended Extensions and Tools -- Use ReSharper for VS Code (`jetbrains.resharper-code`) as the default C# experience in VS Code. -- C# Dev Kit (`ms-dotnettools.csdevkit`) and C# (`ms-dotnettools.csharp`) are discouraged in this workspace. -- Use `ms-vscode.cpptools` for C/C++ editing and IntelliSense. -- Build and test through repo scripts/tasks: +- **ReSharper for VS Code** (`jetbrains.resharper-code`) for C# editing, navigation, refactoring, and test explorer +- **Discouraged:** C# Dev Kit (`ms-dotnettools.csdevkit`) and C# (`ms-dotnettools.csharp`) + (these do not support debugging or test discovery for projects that use .NET Framework, as this workspace still does). +- **C/C++** (`ms-vscode.cpptools`) for C/C++ IntelliSense and debugging. +- **PowerShell** (`ms-vscode.powershell`) for build and test scripts: - `./build.ps1` - `./test.ps1`