Skip to content

Contributing to FieldWorks Development

Jump to bottom
Damien Daspit edited this page May 30, 2017 · 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. 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 Registry Keys] (#3-set-registry-keys)
  4. Build FieldWorks

1. Install Required Software

The following tools are required for FieldWorks development:

Installation of Git

Download the latest version of msysgit (something like Git-1.9.5-preview20150319.exe). Install it including the git-cheetah extension (in "Select Components" dialog select "Windows Explorer integration"/"Advanced context menu (git-cheetah plugin)").

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".

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 Git Bash options

The first time you start Git Bash, you will want to enable paste. Click the icon in the upper-left corner of the window and choose Properties. In the Options tab, make sure the Edit Options checkbox on the right side labeled QuickEdit Mode is checked. Then when you are using Gerrit and you use the little clipboard icon to copy a git command to the Windows clipboard, you can enter it in Git Bash by right-clicking in the window.

If you are running with user access control enabled, you will need to run git bash as an administrator in order for it to be able to save this setting.

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 git://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.

3. Set Registry Keys

Windows x64

If you have not installed FieldWorks using an installer, you will need to create the following registry keys for certain unit tests to pass and possibly for dialogs to work, and to access FlexBridge (bridge to Chorus, used for collaboration features):

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\SIL\FieldWorks]

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\SIL\Flex Bridge\8]
"InstallationDir"="C:\path-to-flexbridge-repo\output\Debug"

Use regedit or simply paste the above into a .reg file and run it.

Alternatively, set the registry keys by running an administrative PowerShell and running these lines:

Reg Add HKLM\SOFTWARE\Wow6432Node\SIL\FieldWorks
Reg Add "HKLM\SOFTWARE\Wow6432Node\SIL\Flex Bridge\8" /v InstallationDir /d "C:\path-to-flexbridge-repo\output\Debug"

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