Oct 16, 2013

git flow for NVDA India branch

[ Note: This information is moving to http://code.google.com/p/saksham-projects/wiki/InNvdaSource ]

NVDA is a open source screen reader for Windows. There is a project underway right now for making sure the feature set required for Indians are contributed to it. This post is an attempt to describe the process and tools.


NVDA has it's own git repository. The 'master' branch is always ready for release, and all the work happens on the per-ticket branch, which are based on master. The  incubation branch is called 'next', on which the ticket-branches linger for testing.

For their work, India team has a repository in bitbucket. This repo completely mirrors the official NVDA repository. It also contains the per-ticket branch that India team members are working on. Finally, it also has the 'in_next' branch, which contains only the work being done by India team members.

When India team members are satisfied with the code in a particular branch, they will update the ticket with the branch / repo information, and also drop mail to nvda-dev mailing list about the feature. From then on,
NVDA maintainers can start their process of incubation in next and then moving in the master for release.

This flow requires the work to be kept 'live' in two branches, the feature branch, as well as the in_next branch. Every few weeks, it's required to merge master into the ticket-branch, and merge ticket-branch into the in_next.


This section lists describes the conventions and git commands
NVDA has the convention of naming branch  as  't1234' for the ticket #1234.
There is another thought process, that branches should be named like 'in_t1234', so that they are different than the one that NVDA team uses.
This will help India  team member identify each other's work.
So any branch that exists in NVDA-India repository, but not in NVDA repository has a 'in_' prefix, and the same purpose as corresponding NVDA repository

Setting up the Repo 

In a empty directory, run following commands:
git init
git remote add nvda git://git.nvaccess.org/nvda.git
git remote add ours git@bitbucket.org:manish_agrawal/nvda.git
git fetch --all
git pull nvda -u master
git pull ours -u in_next
At this point , open readme.txt to see how to compile NVDA.

Starting on a ticket branch

git checkout master  
git pull
git checkout -b in_t1234
git push ours -u in_t1234

Updating work to in_next

git checkout master
git pull
git checkout in_t1234
git merge master
git commit -a
git push
git checkout in_next
git merge master
git merge in_t1234
git push

These instructions and background should be sufficient for someone to get started in contributing to NVDA via the NVDA-India repository.

Some handy git commands

To see exact diff between two branches, use branch1 dot dot branch2

git diff master..t1234
git diff master..
git diff master...t1234
git diff master...

To move back a branch from 'next' to 'master' , we'll have to use the old diff-patch mechanism

# Get the old branch
git checkout t1234
# bring it up to date, replace nvda by the name of nvda remote
git merge remotes/nvda/next
# save the differences
git diff remotes/nvda/next... > patch.1234

# switch to master
git checkout master
# create new branch
git checkout -b in_t1234
# apply the patch
patch < patch.1234
# review
git diff
# commit, push etc..  

List of tickets contributed by India team

git branch -a | grep in_ 

Selecting base branch

Unless really required, the base branch should be master.
If some work is common to multiple tickets, a common branch should be created, rather then
duplicating code in multiple branches.
If the base branch is NOT Master, than branch should be named as 'in_t1234_basebranch'
Git does not provide a way to find the base branch later, so naming convention is important.

1 comment:

  1. Awesome. This is going to be really useful for anyone working with us.