Contributing to CTK

The present document aims at describing how a developer should contribute to CTK.

• The source code of CTK is currently hosted on Github [1]. See http://github.com/commonth/CTK

• It's also assumed the developer is familiar with git. There are countless amount of resources available online. A good start point could the list presented on CMake/git page [2].

• We use a topic-based workflow as documented here and thus define integration branches:
  • master Release preparation; starting point for new features (default)
  • next Development; new features published here first

Prerequisites

• Create an account on github.com
• Fork http://github.com/commontk/CTK
• Introduce yourself

$ git config --global user.name "Your Name"
$ git config --global user.email "you@yourdomain.com"

Checkout your fork

cd MyProject
git clone git@github.com:<MYACCOUNT>/CTK.git
git remote add origin git@github.com:<MYACCOUNT>/CTK.git
git remote add upstream git@github.com/commontk/CTK.git

Publishing your branch

• Having your own fork CTK allows you to backup and publish your work avoiding the hurge to merge [3]

git checkout -b new_feature
hack, hack, hack, add, commit
git push origin topic1:refs/heads/topic1

• As a shortcut, you could also enter the following. Some useful script are also available here:

git config branch.topic1.remote origin
git config branch.topic1.merge refs/heads/topic1

• Then, from the branch new_feature, you could just enter the following to backup/publish your work:

git push

• To delete a branch from your fork:

git push origin :new_feature

Checkout a branch from a different fork

• You may want to collaborate with an other developer and work conjointly on a feature.
• Let's say, jcfr published the branch awesome_feature on his fork. You should do the following to check out his branch:

git remote add jcfr git://github.com/jcfr/CTK.git
git fetch jcfr
git checkout -b awesome_feature refs/remotes/jcfr/awesome_feature

• You should now have a local branch named awesome_feature. You can now add, commit and publish your work.

Integrate your new feature

• Initially, your feature should be integrated to next.
• To integrate your change to next, you could follow the steps listed below. More details are also available here.

git fetch upstream                             # Retrieve change from upstream repository
git checkout next                              # Checkout your local "next" branch
git merge upstream                             # Make sure your local branch is up-to-date.
git merge new_feature                          # Merge locally to "next" - Your changes are now integrated
git push upstream                              # Publish your change on the official repository
git push origin                                # Publish your change on your fork

• After it has been validated and tested, it could be integrated to master. More details here.

Repeat the command listed above changing "next" into "master"

Tutorial

The idea behind the tutorial is the following, it will guide you through the basic step allowing to:

• Prerequisites - Fork and clone the tutorial repository
• Step1 - Create a new feature from master branch
• Step2 - Add and commit a file representing the feature
• Step3 - Merge the feature into the next branch
• Step4 - Refine your feature by doing an additional commit
• Step5 - Merge again with 'next
• Step6 - Merge feature with master

The 'tutorial feature' you will create could be correspond to a TXT file containing either a proverb, sentence, thought of the day, proverb, ...

• For the sake of the tutorial, let's make sure the text you create for the first commit contain an "error" (missing the author name, spell mistake, ...).
• The second commit will intent to fix the "error"

For example:

• Commit1
  • Filename: ghandi.txt
  • Content: "Be the change you want to see in the world." Mahatma Gandhi
  • CommitMsg: Added Mahatma Gandhi proverb about change
• Commit2:
  • New content: "Be the change you want to see in the world." Mahatma Gandhi, Indian philosopher, internationally esteemed for his doctrine of nonviolent protest, 1869-1948
  • CommitMsg: Specified who is Mahatma Gandhi

You will find a repository named GitTutorial here: http://github.com/commontk/GitTutorial

• Prerequisites

• Step1

• Step2

• Step3

• Step4

• Step5

• Step6

FAQ

• What the meaning of fatal: The current branch master is not tracking anything. ?