Archive | September, 2014

How to contribute in an open source project: A step by step guide

4 Sep

Opensource Software is gaining popularity and is the best way of creating software. Opensource projects also give opportunity to learn coding in a real time environment. Being a beneficiary and supporter of opensource software I always want to contribute to it.  But due to lack of technical expertise in “How to contribute?”, I was not able to contribute till now, but today I came across the site “www.openhatch.org” and first time experience the baby steps of contributing towards an opensource project.  Here, I am sharing my learning to help others. 

You can contribute to an opensource project in many ways like documentation, promotion, testing, bug fixing and feature enhancement. Here, I have focused on feature enhancement, but very similar approach is applicable to other task also. Before going any further it is advisable to please go through below link, it will help you to understand the material in greater details.

  1. http://openhatch.org/missions/
  2. http://openhatch.org/missions/diffpatch
  3. http://openhatch.org/missions/git

Opensource Project

Most of opensource project is hosted on google code, github or Bitbucket. From these sites you can get the code for modification.

Tutorial Setup

For this tutorial, I have done special setup to make learning easy.

Project scenario:

1. Suppose there is one developer who is developing a project for finding Even and odd for a given number. He created and hosted project on github.

2. There is another developer who wants to contribute to the finding Even/Odd project.

3. The creator of the project only has right to make final commit /changes to the code.

4. Other developer works and send changes as a patch to the core developer and he makes changes.

Project setup:

1. To mimic the above scenario we develop two github account by logging to the web interface of github.

2. The owner of the project have user name <urwithajit> and he created code repository as oddEven.git

3. The other contributor created a git hub account as <urwithajit9>

How to create a project on the local system and push them to the online github repository?

( As the project core member)

1. Go to your terminal. (I used Ubuntu and we all ready have installed git client, please check web for how to install git?)

2. Create a folder to create your project  $ mkdir myproject

3. Go inside the directory $ cd myproject

4. Create your program $ gedit oddeven.py

5. Initiate your git project

5.1 git init

5.2 git add .

5.3 git commit -m “First commit ,uploading the project to github repo

Note: before pushing your code you must need to sync your online repo for this use 5.4

5.4 git pull https://github.com/<username>/&lt;repo.git> master

In my case <username> is urwithajit and repo.git is oddEven.git ( change accordingly)

Now you can repeat the 5.1 and 5.2 to just avoid any error

5.5 git push

How to fork and opensource project and make necessary changes? ( As as project contributor)

1. Search a project on github on which you want to contribute. For this example, we have chosen the urwithajit/oddEven project.

2. For the selected project on github (have a very good interface on the web)

3. Copy the repository address ( https://github.com/urwithajit/oddEven.git)

4. Now, back to your terminal and come out from the previous folder myproject. ( cd ..)

5. Create a new folder to copy the code locally to work on the fork project. $ mkdir mycontribuation

6. Go inside the folder $ cd mycontribuation

7. Clone the project code locally

git clone https://github.com/urwithajit/oddEven.git

It will automatically download all the files in your local machine. and will create a folder with repo name such as oddEven

8. Go inside the newly created folder $ cd oddEven

9. Make necessary changes to the code like adding function removing function etc.

10. Once you have tested your newly changes to the code you are ready to submit the code to your fork repository which later can be used for making a final pull request to the original code repo.

How to push the changes to the your online fork repository ( urwithajit9/oddEven)?

1. Add the directory to your online repo ( use same link that you use for cloning)

git remote add upstream https://github.com/urwithajit9/oddEven.git

2. Create a difference in code  ( Know as patch, you can also use git format-patch origin/master after adding file for the commit)

git diff

3. Add file/files for commit

git add oddEven.py

4. Commit the changes to your local git client

Git commit -m ” First commit, make changes in the function”

5. Push the code to your fork repo

git push origin master

How to submit patch or changes to the original developer to merge with core repository?

Once you have made changes to any project and have created patches for the same. You can use online web interface of github to a pull request to the core repository. For doing same you just click on the pull request and create a pull request.

Please give a meaning full description of your pull request.

 

How the final merge of the patch will be done in the core code report?

Being the owner of a project you will notify for every pull request via email and on the web interface. For making merge just click on the pull request link and github will show the patch details.

Verify the patch and take action accordingly. To merge the submitted patch just click on merge.

 

Finally, you have contributed to an open source project.  Same flow can be used to fix a reported bug. Reported but have enough detail to get started  and also have a bug ID for making commit and changes more traceable.

This article is based on below tutorial.

http://pyvideo.org/video/1722/contribute-with-me-getting-started-with-open-sou

 

Hope it will be helpful to get started with any open source project. Keep learning and contributing towards open source projects.

Note: This is a one time written post so may have mistakes or ambiguities, please write me for any changes or help.

Happy learning. 🙂