Get involved with Ubuntu Tweak Development
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…
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.
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.
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.
Right, now we can get started. First, use the private url to get your copy of Ubuntu Tweak to your local machine:
git clone [email protected]: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
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)
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:
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.
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.
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