Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
176 lines (113 loc) · 6.05 KB

CONTRIBUTING.md

File metadata and controls

176 lines (113 loc) · 6.05 KB

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 is Windows-only. Linux builds are no longer supported.

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 2022

Download and install Visual Studio 2022 Community Edition or higher. See Visual Studio Setup for detailed configuration.

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.

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.

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.

Switch to Visual Studio 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.

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