Github issue workflow

OpenTX is an open source project with many contributors. By using a common and understandable workflow, we can work together without getting in the way of each other. Luckily GitHub provides us with good tools that makes this easy and enjoyable.

As the name implies, GitHub uses the git revision control system. Git is a more advanced system than e.g. SourceSafe or Subversion and is well suited for distributed collaborations like OpenTX. Git can be used to support many different models for working together. The model used by OpenTX is to have a remote master repository, which is hosted on GitHub, and do the work in local repositories.

The next branch in the master repository holds the unstable development versions of both OpenTX and OpenTX Companion. The software in next should always build and run, but may be more or less functional. Adding code to next is done by the administrators, not by individual comitters.

DO NOT push code directly to next
DO NOT work directly in the next branch.

It is a very bad idea to use development versions of OpenTX software for real life use.
Your plane will crash and burn.
Your pet will get hurt.
You have been warned.

Workflow

• Each committer starts by creating a local version of the master repository.

• New ideas as well as bug reports are called issues. Before any work is started there must be an issue in the issue list of OpenTX. The issue list is hosted on the web by GitHub. The issue is used to discuss the problem/idea with others and report back progress. Each issue has a unique OpenTX issue number.

• When a committer decides to start work on resolving an issue in the project, he first assigns himself to the issue.

• He then creates an issue branch in the remote master repository by branching from the appropriate branch. This is easiest to do by using the Web interface on Github.

  • If issue is marked as milestone 2.1.x branch from master
  • If issue is marked milestone 2.2, then branch from next branch

• The new branch should be called something like committergitname/name_of_the_isue_123 (if 123 is the issue number)

• The next step is to fetch the new branch to the local repository.

• Changes are made and tested within the branch in the local repository.

• When the changes are done, the next branch is pulled down from the remote repository and if there are any conflicts these are resolved.

• The last commit message should read Fixed #123 (if 123 is the issue number). This increases the chance that an administrator will notice that the work is ready to be merged.

• The branch is pushed back up to the remote repository.

• The committer creates a "pull request" on the branch. The easiest way of doing this is to use the GitHub web interface. The request must be made towards next, not master, which is the default.

• When the change is accepted by one of the administrators, it is merged into the next branch.

• The administrator removes the issue branch from the remote repository.

• The administrator closes the issue in the issue list.

• When the solution is merged into master then you port it to the next (2.2.) branch.

Git Clients.

The git command line interface is a complete mess. Nothing like the logical subversion svn commands. Using a graphical client is a must.
Good client alternatives are SmartGit/Hg on Linux/Windows and SourceTree on Windows/OSX.
If you are working on Windows and is used to Tortoise for Subversion, you will probably want to use Tortoise-Git.