Get involved with Ubuntu Tweak Development

tualatrix edited this page Sep 29, 2010 · 1 revision
Clone this wiki locally

Prepare

Ubuntu Tweak’s source code is controlled under Git, a popular SCM tool. A lot of free software projects use Git for source code management, such as Linux, GNOME, X.Org etc.

To develop with Ubuntu Tweak, you will first need to install Git on your system. If you are using Ubuntu do the following:

sudo apt-get install git-core

After installation, you will want to do some basic configuration of your Git setup:

git config --global user.name "Your Git username here"

git config --global user.email youremailhere

git config --global color.ui auto

Now let’s start developing Ubuntu Tweak…

Sign up for a GitHub account

First, you should register at github.com, so that you can have permissions to commit your changes to the Ubuntu Tweak code.

In the registration form, you can paste in your ssh public key. If you don’t yet have a ssh public key, use ssh-keygen in a terminal to generate one. It should then be located at ~/.ssh/id_rsa.pub by default. The ssh key is very important and is used to authenticate with the GitHub servers. Without it you won’t be able to push your changes back to GitHub.

Fork Ubuntu Tweak

After the signup process, log into your GitHub account (The following test account is: ubuntutweak) and visit Ubuntu Tweak Git . Click the “Fork” button to create your own fork of Ubuntu Tweak for development.

Don’t worry about the term “fork”. You must create a fork so as to have your own copy of Ubuntu Tweak to work with and make changes freely. These changes can then be merged back up to the original branch and will eventually be pushed out to users in the next Ubuntu Tweak release.

Get your copy of Ubuntu Tweak and start coding

After forking, you should now have your own copy of the Ubuntu Tweak code. It will be located under your name space: such as ubuntutweak/ubuntu-tweak, (note that the original is tualatrix/ubuntu-tweak).

Now you can start making some changes to the source code.

Downloading the source code

Right, now we can get started. First, use the private url to get your copy of Ubuntu Tweak to your local machine:

git clone git@github.com:ubuntutweak/ubuntu-tweak.git

(Remember to change ubuntutweak to your own username)

Now you can start implementing and committing changes to the source code. When this is done, you can then push all your commits to the GitHub server. If you aren’t familiar with git, you can learn it here: Git book

Basic Commands

To see changes that you have made to the code before commits use the git diff command:

git diff

You can then use the arrow keys to browse changes made to the code. To close this view, simply type q.

To commit these changes use the git commit command:

git commit -a

You will then need to write a brief summary of any changes that have been made to the code and why.

To push your code back to the GitHub server, you can use the git push command:

git push origin master

This pushes the commits you have made from origin (your local machine) to master (your fork on the GitHub servers)

Making changes

In most cases, you will be making changes to some files in the ubuntu-tweak/ubuntutweak/* directory in your home folder to implement bug fixes or do other work on the code. When you want to see your changes in action, just run ubuntu-tweak/ubuntu-tweak and you can play with your new updated Ubuntu Tweak immediately.

If you want to improve the English strings that make up the Ubuntu Tweak user interface, please note that you should always change the strings within _("") quotations, this then allows them to be easily translated into other languages.

Now assume that you have committed and pushed a change named: TEST: change a string. As in the screenshot below:

Send pull request

You will now want to pull your changes back to the original branch (tualatrix/ubuntu-tweak). You should send a pull request to notify the author about what changes you have made to the Ubuntu Tweak code (hence the importance of annotating your commits). Click the pull request button that is at the top of your Ubuntu Tweak fork homepage.

A popup window will appear. Enter your message to the author – possibly outlining some of the key changes made to code and their purpose. Under Recipients select tualatrix, then press Send Pull Request.

Start merging your work

Shortly after the pull request has been made, I (the original author of Ubuntu Tweak) will receive your message as below:

After reviewing your changes, I will either consider to merge your work back into the original copy, or reject any merges giving a reason.

If I accept your work, any changes that you made to the code will then be reflected in the original copy and later pushed out to Ubuntu Tweak users. That’s how the work-flow of git goes.

Keeping up to date

You may want to know how to keep your branch and the original Ubuntu Tweak branch up to date and in sync.

First, add the original branch as a separate remote source, you should only complete this step once.

git remote add tualatrix git://github.com/tualatrix/ubuntu-tweak.git

Each time you want to download and merge the latest code from the original branch, simply enter the following commands

git fetch tualatrix

git merge tualatrix/master

There may be some conflicts between your branch and the original, you will need to resolve these yourself.

That’s it! If you want to know more about the development of Ubuntu Tweak, please send me an email. Thanks!

My email is: tualatrix AT gmail.com