Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
212 lines (137 loc) · 8.22 KB

CONTRIBUTING.md

File metadata and controls

212 lines (137 loc) · 8.22 KB
Raw

Contributing to FieldWorks Development

Thank you for your interest in contributing to FieldWorks (FLEx)!

Ways to Contribute

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

Getting Started

The following steps are required for setting up a FieldWorks development environment on Windows.

Note: FieldWorks build, test, installer, and setup workflows are Windows-only. Linux and macOS are supported for editing, code search, documentation, specs, and agent work only.

1. Install Required Software

Git

Download and install the latest version of Git.

During installation:

  • On "Adjusting your PATH environment": Select any option you want - "Use Git Bash only" is sufficient unless you want to run git commands from the Windows command prompt.
  • On "Configuring the line ending conversions": Select "Checkout Windows-style, commit Unix-style line endings".

Visual Studio 2026 or 2022

Download and install Visual Studio Community Edition or higher (2026 preferred; when both are installed the build uses the newest). See Visual Studio Setup for detailed configuration, or import the repo-root .vsconfig in the Visual Studio Installer.

Required workloads:

  • .NET desktop development
  • Desktop development with C++ (including ATL/MFC)

WiX Toolset (v6 via NuGet restore) (for installer building)

Installer builds use SDK-style .wixproj projects and restore WiX v6 tooling via NuGet during the build.

.\Setup-Developer-Machine.ps1

See Installer Build Guide for building installers locally.

Windows Defender Exclusions (Recommended)

FieldWorks builds can be significantly slowed by Windows Defender real-time scanning. To configure exclusions, run the following in an Administrator PowerShell:

.\Build\Agent\Setup-DefenderExclusions.ps1

This adds exclusions for build outputs, NuGet caches and development tools. Use -DryRun to preview changes without applying them.

If you also work in sibling repos in the same parent folder (e.g. PanGloss, motif, foma-rs), run ..\Setup-DefenderExclusions.ps1 instead (one level up) — it covers this repo plus the Rust toolchain (.cargo/.rustup) and CMake/Rust process exclusions the FieldWorks-only script doesn't need.

2. Clone the Repository

Clone the FieldWorks repository using HTTPS or SSH:

HTTPS:

git clone https://github.com/sillsdev/FieldWorks.git
cd FieldWorks

SSH:

git clone git@github.com:sillsdev/FieldWorks.git
cd FieldWorks

Optional: Clone FwLocalizations (for translation work)

If you're working on translations:

git clone https://github.com/sillsdev/FwLocalizations.git Localizations

Set up fonts for Non-Roman test data

Install the PigLatin font by right-clicking on DistFiles/Graphite/pl/piglatin.ttf and selecting Install.

3. Set Environment Variables

Add the following environment variables:

# Prevent sending usage statistics
$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)
$env:FIELDWORKSDIR = "C:\path-to-repo\Output\Debug"

Tip: Add these to your PowerShell profile or system environment variables for persistence.

4. Build FieldWorks

Build FieldWorks using the PowerShell build script:

.\build.ps1

For more build options, see .github/instructions/build.instructions.md.

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

Use test.ps1 for local test runs:

.\test.ps1
.\test.ps1 -TestProject "Src/Common/FwUtils/FwUtilsTests"
.\test.ps1 -SkipManaged -TestProject TestGeneric

By default, test runs suppress FieldWorks assertion dialogs so unattended runs cannot hang on Abort/Retry/Ignore UI. For a local debugger session where you intentionally want the previous interactive assertion dialog behavior, use the command-line switch:

.\test.ps1 -SkipManaged -TestProject TestGeneric -AllowAssertDialogs

The environment-variable equivalent is FW_TEST_ALLOW_ASSERT_DIALOGS=1:

$env:FW_TEST_ALLOW_ASSERT_DIALOGS = '1'
.\test.ps1 -SkipManaged -TestProject TestGeneric
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

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.

If you are a core developer using GitHub Copilot or Claude Code, follow AI-Assisted PR Workflow 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.

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

See VS Code Stability Profile for current workspace guidance.

Git Configuration Tips

It is helpful to increase the rename limits for Git to properly detect renames in large commits:

git config diff.renameLimit 10000
git config merge.renameLimit 10000

Contributing Code

General Guidelines

  • Write tests: For any new functionality and when modifying existing code, write NUnit tests. This helps others not introduce problems and assists in maintaining existing functionality.

  • Follow formatting and commit conventions: Use .editorconfig for formatting and see commit message guidelines for CI-enforced commit rules.

  • Make sure tests pass: Ensure all tests pass before submitting. Tests are directly integrated into our build system.

Contributing Changes

We welcome any contribution! To get started:

  1. Fork the FieldWorks repository on GitHub
  2. Clone your fork locally
  3. Create a branch for your changes: 
    git checkout -b feature/my-feature-name
  4. Make your changes and commit them with clear messages
  5. Push to your fork
  6. Submit a pull request to the main repository

See workflows/pull-request-workflow.md for detailed PR guidelines.

Core developers doing AI-assisted work should start with AI-Assisted PR Workflow instead of jumping directly to the generic PR checklist.

Becoming a Core Developer

People we know well might be asked to join the core development team. Core developers get additional privileges including the ability to make branches directly in the main repository and contribute in additional ways.

Getting Help

  • Documentation: Check the docs/ folder for additional guides
  • Issues: Search or file issues on GitHub
  • Wiki: Historical documentation at FwDocumentation wiki (being migrated to this repository)

See Also