Skip to content

Contributing to FieldWorks Development

Jump to bottom
papeh edited this page Sep 29, 2022 · 51 revisions

Thanks for your interest in contributing to the FieldWorks development!

Ways to Contribute

There are several ways you can contribute to the development of FieldWorks:

  • Contributing code
  • Testing alpha and beta versions

The instructions below are for setting up a FieldWorks development environment on Windows. If you prefer to develop on Linux, please see this wiki. If you want a single script to handle the setup for you (and uninstall Windows bloatware), click here. Do return here for our general guidelines for contributing code

Getting started with contributing changes

The FieldWorks project consists of several git repos. To make setup easier we created several scripts in the fwmeta.git repo.

The following steps are required for setting up for FieldWorks development:

  1. Install Required Software
  2. Clone the git repos
  3. Set Environment Variables
  4. Build FieldWorks

1. Install Required Software

Installation of Git

Download and install the latest version of git.

On the dialog "Adjusting your PATH environment" you can select any option you want - "Use Git Bash only" is sufficient unless you want to run git commands from the windows command prompt.

On the dialog "Configuring the line ending conversions" select "Checkout Windows-style, commit Unix-style line endings".

Installation of dotnet

Download and install the latest .NET SDK (presently 6.0.401) from https://dotnet.microsoft.com/en-us/download/dotnet/6.0

Installation of Visual Studio

Download and install Visual Studio 2017.

Visual Studio 2017 (You may use the Visual Studio Community Edition). See Set Up Visual Studio for FieldWorks Development on Windows.

2. Clone the git repos

Start by cloning the fwmeta.git repo and running the fwmeta/initrepo script. Open a Git Bash window. Then run the following commands. It is assumed that you will install the FieldWorks source code in subdirectories of c:\fwrepo. If you want to put it somewhere else you will have to adjust the commands accordingly:

cd /c/
git clone https://github.com/sillsdev/fwmeta.git fwrepo
cd fwrepo
fwmeta/initrepo

(Note that you must run fwmeta/initrepo from fwrepo, not fwrepo/fwmeta.) The initrepo script will ask several questions and give the opportunity to specify the repos that you want to clone, as well as the branches you want to clone.

The following two repos are essential if you make any changes to the FW source code: FieldWorks and FwSampleProjects.

You need at least the branches master and develop.

If you later need to get more projects or branches, you can execute fwmeta/initrepo --modify to make it give you a chance to change your answers. fwmeta/initrepo --help gives full details.

It is also helpful to increase the rename limits for Git, so that it can properly detect renames for large commits. You can increase the limits to something like 10,000 files by executing the following commands:

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

Set up fonts needed for Non-Roman test data

Install the piglatin font (by right-clicking on $FWROOT/DistFiles/Graphite/pl/piglatin.ttf and selecting Install).

3. Set Environment Variables

To prevent sending usage statistics, add the following environment variable:

FEEDBACK=off

To set things up for debugging projects that use ICU (In FieldWorks 9.1.11, we upgraded from ICU 54 to ICU 70)

ICU_DATA=C:\path-to-flex-repo\DistFiles\Icu70\icudt70l

To prepare for working with a development version of FlexBridge (FIELDWORKSDIR is also used by Paratext to find ICU DLL's)

FIELDWORKSDIR=C:\path-to-flex-repo\Output\Debug
FLEXBRIDGEDIR=C:\path-to-flexbridge-repo\output\Debug\net461

4. Build FieldWorks

See the Building FieldWorks wiki page.

Contributing Code

General remarks

For developers we ask that you write NUnit tests for any new functionality and when modifying existing code - in other words: always. This will give you an insight beyond what the documentation states about the class. Then you should implement the code.

This is useful because once you submit the code it will help others not introduce problems in code that you depend on. And if the code needs to be maintained and extended it will assist us in not breaking existing functionality that is implemented.

You should make sure that all tests pass. Then these tests can be directly integrated into our build system.

Please also have a look at our Coding Standard. Note that our coding format is different from the default style from Visual Studio.

Contributing changes

We welcome any contribution. For new people we ask that you send your patch by email to gerrit at sil dot org (patch should be prepared by running git format-patch), or by cloning the FieldWorks repo and submitting a pull request. This is so that we get to know you.

People we know well might be asked to join the core development team. They have to follow some additional setup steps and follow our Git/Gerrit/Jenkins workflow.

Workflow for sending patch by email

  • make code changes and test locally
  • do a full remakefw and make sure all tests pass (build /t:remakefw /p:action=test)
  • commit the change locally
  • format the patch (git format-patch -1)
  • send email with the patch to gerrit at sil dot org
Clone this wiki locally