Contributing to ODTBX:

A Guide for MacOSRavi Mathur

Updated December 5, 2012

2

ODTBX uses Git (see the ODTBX Git Tutorial)◦ SourceForge account needed (free).

Recommended Git Clients◦ Command Line: Built-in git client. Get it by

installing XCode (available from App Store), then going to XCode Preferences Downloads Command Line Tools. Use the command-line version of this tutorial.

◦ SourceTree is a free full-featured GUI client for Mac. This guide assumes SourceTree is being used, but other GUI clients will have similar functionality.

Introduction – Git Clients

3

SourceTree Clone Repository: File New ODTBX URL:

◦ ssh://username@git.code.sf.net/p/odtbx/git

Get the ODTBX Repository

1: Your SourceForge username (enter password later)

2: Desired repo location3: Desired SourceTree name

4: Clone it! (~400MB download, may take time)Read do’s and don’ts while waiting…

4

Make sure your name & email are set in Git◦ You should get credit for your work!◦ SourceTree: Preferences… General

Submit code for one feature at a time.◦ Repeat this process for each feature to submit.

Comment and organize your code◦ Make it easy for ODTBX developers to understand

and incorporate your code into ODTBX. Test your code before submitting

◦ Needs no explanation…

Contributing – Do’s

5

Don’t use the repo to “dump” documents◦ EVERYONE will download EVERYTHING you

submit!◦ We don’t want to bloat the main ODTBX repo.◦ Use the ODTBX webpage for this (ask Admin).

Don’t commit audio/video/multimedia files. ◦ Exception: files that are necessary for code to

work (e.g. graphics needed by a custom GUI).◦ Exception: articles/papers directly explaining

algorithms used in your code. Don’t commit ITAR/sensitive code

◦ The SourceForge repo is VERY public!!

Contributing – Don’ts

6

ONLY DO THIS STEP IF:◦ You need to test your code with ODTBX.◦ Otherwise, skip this entire slide (e.g. if you are

just submitting code for review). On the ODTBX Developer Wiki

◦ Follow the “Tools & Environment Setup” page.◦ Make sure you set up your startup.m file.◦ Test by running estbat_test in Matlab.

It should return 0 (zero) if successful. Don’t worry about warnings from the test.

ODTBX Developer Setup

7

If you know Subversion, FORGET SUBVERSION.

Git branches are VERY light, VERY easy to use.

Branches in Git

Currently Checked-out Branch (in bold)Double-click to checkout “develop” branchALWAYS start from the “develop” branch!!

8

Start by checking out the “develop” branch. SourceTree: Repository Branch…

Verify that your branch is checked out!

Step 1: Create a Branch

MUST branch from “develop”!!Short descriptive branch name

9

Create new folder at root of your ODTBX repo◦ All your files (source, documents, etc…) go in

here.◦ Use the same name as your branch.◦ Only add files to odtbx/ or vendor/ folders if you

were approved to do so.

Step 2: Organize Your Files

Your folder: Organize your submission files in here

10

Step 3: Add Your Files to Repo

1: Make sure your branch is checked out2: Select “Working Copy”3: Select your code folder4: “Add” folder to the repo

11

Step 4: Commit Your Files

1: “Commit” work to your repo2: Add commit message - Check Author Name & Email

12

Get permission from ODTBX admin first!◦ Request access to ODTBX “contributor” group

SourceTree: Repository Push…

Step 5: Submit Your Branch

1: Select your branch to push it to SourceForge - Unselect “develop”

2: Push it! Everything committed to your branch will be added to SourceForge.

✔

13

Inform ODTBX Admin(s) of contribution◦ Include your branch name

Your files will be evaluated…patience!◦ Code evaluation will be done by ODTBX

developers … you may be asked for clarification.◦ Code incorporation can be tracked by doing a Git

“Pull” while your branch is checked out. SourceTree: Repository Pull…

You will have to do “Developer Setup” to test your files within ODTBX.

Wrap-Up Submission

14

Thank you for your submission! ODTBX Admins listed on SourceForge

◦ http://sourceforge.net/projects/odtbx/

Conclusions / Notes