-
-
Notifications
You must be signed in to change notification settings - Fork 2
Getting Started for Core Developers
This document describes the steps necessary to setup for development for a core developer. Unless you know that you fall into that category you may want to follow the steps in [Contributing to FieldWorks Development](Contributing to FieldWorks Development) instead.
The FieldWorks project consists of several git repos. To make setup easier we created several scripts in the fwmeta.git repo. Besides cloning the repos you'll also have to register with some services we use if you want to actively contribute to the project.
Any core developer should follow the steps in Contributing to FieldWorks Development first and then perform the following steps:
You should register with our Gerrit code review server.
Gerrit uses OpenID and OAuth2 for authentication; you can use your existing Google or GitHub account for that, or create an account with another OpenID provider and enter the URL of your OpenID. If your OpenID provider supports it you should enter an https version of the URL otherwise you might get a warning from your browser.
Once you've registered an OpenID, you will be asked to choose a user name. It's preferable to use firstname_lastname in all lowercase characters. You should also set a real name, which is what other users will see in the UI.
You can also register a preferred email address (eg @sil.org) that's different from the one that may be associated with your OpenID. If you have problems with the link that you are sent for validating your email address, try viewing the email in webmail since some email client programs may mangle the long, cryptic URLs that are sent.
In order to be able to modify the documentation on the wiki on GitHub you need a GitHub account.
In order to be able to restart or kill stuck builds, you need to create an account on our Jenkins continuous integration server. Again, your username should be firstname_lastname in all lowercase characters. Further instructions will be sent on request by sending an email to gerrit at sil.org.
Alternatively, you can just contact a Jenkins administrator for help when the need arises. Build results can be viewed on our public Jenkins server without being logged in. (JM 12/2023: This link just takes you to a login screen, and after logging in you get an Access Denied page if you don't have permissions.)
After creating accounts on Gerrit, GitHub, and Jenkins please send an email to gerrit at sil.org telling your usernames on these three services so that you can be given the correct permissions.
Uploading changes to Gerrit is done through ssh. Gerrit needs to know your public key for identification. This means that you have to create and upload an ssh key. If you are setting up on more than one computer, it is OK (and more secure, Eberhard says) to make a new one for each computer.
When you have git installed run git gui (on the Windows Start Menu, choose Programs > Git > Git GUI, or run git gui in a terminal in Linux). Choose Help > Show SSH Key and click on the click the Generate Key button. When the key is generated click on the Copy To Clipboard button. Then log in to Gerrit and go to <your username in the upper-right corner>, Settings, SSH Public Keys tab. Click the Add Key button and paste your SSH key from the clipboard.
To verify your SSH key is working correctly, open a terminal window (on Windows: git bash window) and connect to Gerrit's SSHD port (replacing firstname_lastname with your gerrit username):
$ ssh -p 59418 firstname_lastname@gerrit.lsdev.sil.org
**** Welcome to Gerrit Code Review ****
Hi Firstname Lastname, you have successfully connected over SSH.
Unfortunately, interactive shells are disabled.
To clone a hosted Git repository, use:
git clone ssh://firstname_lastname@gerrit.lsdev.sil.org:59418/REPOSITORY_NAME.git
Connection to gerrit.lsdev.sil.org closed.
This might ask if you want to continue because it doesn't recognize Gerrit's public key (fingerprint of Gerrit's public keys are 8c:66:e0:e9:f4:f2:ea:90:25:0e:05:76:2b:c1:03:6f, b2:e0:ea:b8:ba:a1:4c:70:38:0a:63:24:8e:76:a9:65, 28:f0:12:8f:1d:e4:d9:f5:10:f2:f6:57:45:5d:43:fa, 84:49:fb:3e:64:bd:8c:e4:cc:19:27:30:be:00:3f:6e, and 90:7a:88:2e:79:2c:41:b1:c6:9c:5b:62:6c:af:5a:04). Answer yes to add the key to the list of authorized keys.
You may be tempted to upload your GPG key. Don't do it. Other developers who tried have lost their permissions until they removed the GPG keys from their accounts.
Important: before starting this step you MUST register your SSH key and obtain permission to be part of the project as described above.
You will need to clone a copy of fwmeta. The easiest way to do this is:
cd /c
git clone https://github.com/sillsdev/fwmeta.git fwrepo
Start by running the initrepo --reset script. On Windows, open a Git Bash window. Then run the following commands:
cd /c/fwrepo
fwmeta/initrepo --reset
This 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. "Currently"(currently keeps changing) you will also need release/9.1.
(If you get an immediate "permission denied" message you may not have uploaded your SSH key successfully. Another possibility is that the GitHub server has gone down, or your internet connection. Apparently "permission denied" is a generic message covering all cases where the server does not respond. If you get it at the "Installing Hooks" stage this may be because you failed to upload your public key to Gerrit. Installing hooks should ask for your SSH passphrase.)
(If you later need to get more projects or branches, you can execute initrepo --modify to make it give you a chance to change your answers. initrepo --help gives full details.) In order to see which branches you can get run the following commands in Git Bash:
cd /c/fwrepo/fw
git ls-remote (this lists all branches and tags)
cd ..
fwmeta/initrepo --modify (put in the branch you want to get, eg hotfix/8.1.3)
cd fw
git branch -a (This will show 8.1.3 on remote)
git checkout hotfix/8.1.3 (This will produce a local copy)
This did not allow bug fixes to be performed on hotfix/8.1.3 so resulted in the following error:
git start task hotfix TryAnIssue
fatal: Cannot setup tracking information; starting point 'origin/hotfix/8.1.3' is not a branch
To correct the problem the following commands were performed:
git config --add remote.origin.fetch +refs/heads/hotfix/*:refs/remotes/origin/hotfix/*
and
git config --add remote.origin.push +refs/heads/hotfix/*:refs/for/hotfix/*
If initrepo gets deleted which happens sometimes when it is run, then run the following:
cd /c/fwrepo/fwmeta
git checkout initrepo