-
-
Notifications
You must be signed in to change notification settings - Fork 2
Contributing to FieldWorks Development
Thanks for your interest in contributing to the FieldWorks development!
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
The FieldWorks project consists of several git repos. You may need more then one depending on the area you wish to contribute to.
The following steps are required for setting up for FieldWorks development:
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".
Download and install the latest .NET SDK (presently 6.0.401) from https://dotnet.microsoft.com/en-us/download/dotnet/6.0 as well as dotnet-runtime-5.0 (required for I forget which build task) and dotnet-runtime-2.1 (if you plan to build localizations).
Download and install Visual Studio 2022.
Visual Studio 2022 (You may use the Visual Studio Community Edition). See Set Up Visual Studio for FieldWorks Development on Windows.
For the minimum development setup you will need to clone the FieldWorks repository (https://github.com/sillsdev/FieldWorks)
You may also want to clone the FwSampleProjects and the Helps projects. To have Helps available in your development environment clone https://github.com/sillsdev/Helps into the DistFiles\Helps folder under your FieldWorks folder.
You can clone FwSampleProjects (https://github.com/sillsdev/FwSampleProjects) to any convenient location so that you can have good sample data for testing and developing FLEx.
If you are going to build localizations you will also need to clone the FwLocalizations repository (https://github.com/sillsdev/FwLocalizations) into a Localizations folder under the FieldWorks.
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
Install the piglatin font (by right-clicking on path-to-flex-repo/DistFiles/Graphite/pl/piglatin.ttf and selecting Install).
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
See the Building FieldWorks wiki page.
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.
We welcome any contribution. To get started fork the FieldWorks repo in Github, clone it, make your changes and submit 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 will get the additional privilege of being able to make branches and PRs from the main repository and contribute in additional ways.