The open source CloudTurbine software is hosted on GitHub (https://github.com/cycronix/cloudturbine), which is a Git-based version control web service. This post introduces some Git and GitHub features and procedures you can use to participate in CloudTurbine development.
- Contributing Content
- Updating Repository
- Git integration in Android Studio
- Markdown Language
An overview of Git and GitHub concepts, procedures, and structure is presented in the workflow diagram below. As you can see, a number of copies of CloudTurbine code reside in several locations, both in GitHub as well as on your local machine. (The diagram below was inspired by both https://www.quora.com/What-is-the-difference-between-an-unstaged-and-an-untracked-file-in-Git as well as Figure 7-2 in Scott Chacon and Ben Straub’s book Pro Git, available for free at https://git-scm.com/book/en/v2.)
- upstream repository: This is the “official” GitHub repository containing the software project you would like to participate in. For CloudTurbine development, this is the repository identified by the URL https://github.com/cycronix/cloudturbine.git.
- fork: Make a copy of the upstream repository to your personal GitHub account (i.e., the copy resides server-side). “Forks” are used in centralized repository services such as GitHub and Bitbucket, but they aren’t specifically a Git concept. The copy in your GitHub account will be known as the “origin” repository and is identified by a URL specific to your account. In the figure above, you can see that the forked CloudTurbine copy that resides in my GitHub account is at https://github.com/jpw-erigo/cloudturbine.git.
- clone: Make a local copy (i.e., to your local computer) of a remote repository. For CloudTurbine development, you will clone the repository from your personal GitHub account; that is, you will make a clone of the forked repository. This can be done either using the “git clone” command or using a tool such as GitHub Desktop.
- branch: A separate work area within a repository; a repository always has at least one branch, typically called “master”. In fact, after you clone a repository to your local machine, the master branch is automatically checked-out and available to be worked on.
- staging area/index: Git keeps track of the status of files that are part of the branch that has been checked out. Files that were part of the branch when it was checked out are “tracked”. Using SHA-1 checksums, the “index” knows when changes have been made to these files since their last commit. If a new file has been added to the working directory (i.e., it hasn’t been checked-in to the repository yet) it is an “untracked” file; that is, the index doesn’t know about this file yet.
- working directory: This directory contains the files for a particular checked-out branch. This is where the user edits, adds and removes files. Files which have been edited, added or removed are updated in the staging area using the “git add” command and then committed to your local repository using the “git commit” command.
A good description of the three local repository areas mentioned above (the locally cloned repository, the staging area or index, and the working directory) is found in the section titled “The Three Trees” in chapter 7 of Scott Chacon and Ben Straub’s book Pro Git.
Participating in CloudTurbine development
There are three ways you can make a desired change in the CloudTurbine code:
- If you have push/write permission to the official CloudTurbine repository, then you can make a clone of this repository and directly push changes to it. As is probably typical of open source development projects, it is a very small group of developers who have write permission to the official CloudTurbine repository.
- You can fork the official CloudTurbine repository, make changes to your fork and then issue “Pull Requests” to the official repository to request that the changes be integrated into CloudTurbine.
- You can fork the official CloudTurbine repository, make changes to your fork and (subject to generous terms in the Apache 2.0 open source license) publish your own version of CloudTurbine.
We anticipate that most collaborators will participate in CloudTurbine development using the second method (i.e., by issuing Pull Requests). In this case, you will “fork” the upstream CloudTurbine repository and then clone your fork to your own computer. From the standpoint of the local clone on your computer, the “origin” repository is the fork under your GitHub account and the “upstream” repository is the official CloudTurbine repository managed by Cycronix at https://github.com/cycronix/cloudturbine.git. As shown in the figure under the Introduction tab, the workflow to make changes in this typical scenario is as follows:
- git checkout: Checkout the branch you wish to make changes to; it can be useful to create a new development branch which will isolate one group of related changes.
- git add: After making changes to the software files (editing, adding, and removing files), add them to your local “staging area” using the “git add” command.
- git commit: Commit changes to your local repository using the “git commit” command.
- git push: Push changes from your local repository to the forked repository under your GitHub account. This can be done using the “Sync” button in GitHub Desktop or using the “git push” command.
- Pull Request: In GitHub, issue a “Pull Request” to the upstream CloudTurbine repository. A CloudTurbine manager will review the request and consider whether this change should be included in the official code.
To update a forked repository with changes from the upstream repository
A forked repository on GitHub (and correspondingly your clone of the forked repository which resides on your local machine) will get out of sync compared to the upstream repository when commits from other users have been merged with the upstream repository. Here are three methods that can be used to update the forked repository.
Method 1: Using GitHub Desktop
- When changes have been made to the upstream repository, GitHub Desktop enables the “Update from repo_name” button near the top of the user interface; for instance, when CloudTurbine is the upstream repository, this button will display “Update from cycronix/master”
- Click the “Update” button; changes will be made to your local clone of your forked repository
- You then need to push these changes to the forked repository which resides in your account on GitHub (i.e., to the “origin” repository); do this by clicking the “Sync” button in GitHub Desktop
Method 2: using local git commands
Using git commands, you can fetch updates from the upstream repository (i.e., the official CloudTurbine repository) to your local clone and then push changes from your local clone up to your fork in GitHub. The instructions at https://help.github.com/articles/syncing-a-fork/ explain how to do this (essentially the same instructions are given at http://stackoverflow.com/a/19506355 with some additional description, including how to add a new “remote”).
Very briefly here’s what you will do:
- Your local clone must have a “remote” that points to the upstream repository (the official CloudTurbine repository). If it does not have this, then add it with a command like the following:
- git remote add upstream https://github.com/cycronix/cloudturbine.git
- Verify you have the new remote by executing: git remote -v
- Fetch updates from the upstream repository; these will be put in a local branch called “upstream/master”
- git fetch upstream
- Make sure you are on the master branch of your local repository
- git checkout master
- Merge the changes you have fetched and are currently stored in “upstream/master” into the master branch of your local repository
- git merge upstream/master
- At this point your local “master” branch and the remote upstream/master branch (the official CloudTurbine repository) are synchronized. Now, to push changes from the local “master” branch to the master branch on your forked copy of the repository in your GitHub account, do the following:
- git push origin master
Method 3: using GitHub
Instructions below are a slightly edited version of what is found at http://stackoverflow.com/questions/7244321/how-do-i-update-a-github-forked-repository
- Open your fork repository on GitHub
- If the fork is behind the upstream repository, you will see a message like “This branch is XYZ commits behind repo_name.” For example, “This branch is 1 commit behind cycronix:master.”
- Click the “New pull request” button
- By default, GitHub will compare the upstream repository with your fork; there should be nothing to compare if you didn’t make any changes in your fork.
- Click on “switching the base” link (if no changes were made in your fork) or click Edit and switch the base manually. Now GitHub will compare your fork with the upstream repository, and you should see all the latest changes.
- Click on “Create pull request” button to create a pull request for this comparison
- Assign a name to your pull request (e.g., “Update from upstream”).
- Click on “Create pull request” button.
- On the new page that pops up, scroll down and click the “Merge pull request” button and then “Confirm merge” button. If your fork didn’t have any changes, you will be able to merge it automatically.
- If you have a clone (i.e., a local copy) of this forked repository, then you also need to do a Pull to update the local clone; this can be done by clicking “Sync” in GitHub Desktop or using the “git fetch” or “git pull” commands (“pull” does the equivalent of a “fetch” and a “merge”).
Whichever one of these three methods you use, at the end of this process, the “master” branch on all three repositories involved should be in sync:
- upstream: the official CloudTurbine repository
- origin: your forked CloudTurbine repository which resides in your personal GitHub account
- local: the clone of your forked CloudTurbine repository
For a brief discussion of the integration of Git into Android Studio, see the “Import into Eclipse and Android Studio” tab at http://www.cloudturbine.com/gradle/.
“Markdown” language on GitHub
GitHub supports a number of different markup languages for rendering files (https://github.com/github/markup). One of these is a plain text encoding called “Markdown”, which can be converted to HTML. Files which use Markdown syntax have a “.md” file extension (for example, the “README.md” file found at the top of many GitHub projects). A neat feature of Markdown is that the tags are meant to be unobtrusive, such that the plain text file should be readable. As John Gruber (Markdown creator) says “Readability…is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.” (https://daringfireball.net/projects/markdown/syntax)
For further information on Markdown, click the Daring Fireball link above or try the following links: