OpenTX Git Development Workflow

Working with Git

When you want to help out with coding for the OpenTX project you will have to deal with the git source control system. If you are not familiar with programming, you can see git as a kind of database for source code. Each time a source file is changed, it is entered into the database and used to build the programs. The old versions of the file are however kept intact and can be retrieved again. Git is the mechanism that makes it possible to work together on the projects without risking the integrity of the project each time a member changes a file.

Git forks

In Git lingo, a fork is simply a duplicate copy of a repository (project). When you create a fork you're making your very own copy of the entire project, to which you can do anything you want, unlike the main repository to which you would not have write access. Github makes it very easy to create a fork, and keep a link to the original repository it was created from to allow submitting work to it easily.
On OpenTX we recommend new and/or inexperienced developers to initially create their own fork to work in. Eventually once they get used to the process and our coding conventions we will give them write access to the main repository.

Git Branches

It is possible to have many parallel development activities going on in the same project by using git branches. You can see the branches as separate copies of all the documents in the project.
When you work on a change, you should do so in a private branch which you create before you start changing things. A document may be changed at the same time in two branches and at a later point be combined again.
Combining branches is called merging and is a very common git procedure.
When you work with git, you change your files on your local machine and store them in your local git repository. Saving a file to your local repository is called committing.
When you are done you can upload your committed files to the github server by pushing the files to the server. You keep committing and pushing until all the work is completed. You then make a request for your working branch to be merged into the original project's repository. This is called making a pull request.

OpenTX may have multiple active branches at a given time, they are named per the matching major version (e.g. 2.1, 2.2). Which is the recommended one to work in will change over time so needs to be discussed with the developers.

Summary:

• You will start by creating your own fork of OpenTX on Github
• You will clone that fork into a local repository on your own computer using a Git client
• You will add the main OpenTX repository as a second remote for your local repository

When you want to work on a particular thing:

• You will checkout the most appropriate branch depending on what your work should be based on following discussion with the OpenTX developers
• You will pull the current status of OpenTX's branch into yours to start from where things are standing in the main project
• You will create a branch in your local repository, based on the checked out branch
• You will code your feature/change, possibly in several steps, committing your work to your branch regularly
• You will push the new commits from your local repository to your Github fork online regularly
• Once you are finished with your work, you will open a pull request between your branch and the branch it was based on in the main OpenTX repo
• You will get comments, advice, requests about your work, which may require you to code/commit/push changes, which will automatically update the existing pull request
• When the OpenTX developers are happy with your work they will merge the pull request, thereby including your work into the main codebase
• Time to party!