Port articles from Medium in the form of Markdown files

[OrkoHunter]

I am on it.

[OrkoHunter]

https://medium.com/kharagpur-open-source-society/breaking-github-down-fa981e6286e7

# Breaking GitHub Down

During my mid semester exams, one night I was getting bored so I decided to
check how to break the most used code hosting website
[GitHub](https://github.com/). I wrote a
script[[1]](https://github.com/DefCon-007/Commiter-source) to add infinite
commits to a repository named
“Commiter”[[2]](https://github.com/DefCon-007/Commiter). It added a dot at the
end of a text file after every commit. The script pushed to the master branch
after every 10,000 commits and then after 1,00,000 commits it deleted the
repository and then cloned it back with just the last commit. I had to do it
because after a large number of commits the directory size was quite
large(approx 7–9 GBs).

With the help of this script I was able to find three bugs on GitHub after which
they blocked my repository[[2]](https://github.com/DefCon-007/Commiter) .

1.  **Z-index for commit label of contribution graph was not proper** :

Below is the screenshot of the issue I am talking about.

![](https://cdn-images-1.medium.com/max/800/1*RTWPIaRI0H0hm0FCwxsZlg.png)
<span class="figcaption_hack">Issue #1</span>

The label for the commit number should be above the graph. I got the following
response for this issue.

![](https://cdn-images-1.medium.com/max/800/1*nlqHSF2LRW8qJ5t3J34cvg.png)
<span class="figcaption_hack">Reply for issue #3</span>

**2. Latest commit info was not loading :**

After some days the I noticed that the GitHub was failing to load the latest
commit information on the repository homepage.

![](https://cdn-images-1.medium.com/max/800/1*Z4JGEWJ5rZYt_xMtsTu_oA.png)
<span class="figcaption_hack">Issue #2</span>

And for this issue I got the following reply.

![](https://cdn-images-1.medium.com/max/800/1*ZS_cheHLvv5xxdFYQyuGEA.png)
<span class="figcaption_hack">Reply for issue #2</span>

**3. Contributions graph failing to load :**

According to me this was a major bug. The contributions graph stopped loading.
It showed the below screen for hours and then the page said “Failed to load
contributions graph”.

![](https://cdn-images-1.medium.com/max/800/1*H7bPVHj9h4VJn5ABHz9JGQ.png)
<span class="figcaption_hack">Issue #3</span>

Sadly this was the last issue I was able to track. After reporting this people
at GitHub disabled access to my repository. The reason stated by them was :

> The repository you’re inquiring about, DefCon-007/Commiter, has been deemed
> abusive to our system and we have disabled it.

> Large numbers of commits do not lend themselves well to versioning with Git and
> performance issues with a repository of this size can endanger the availability
of your repo as well as other user’s repositories. Additionally, the pattern of
your commits is very different than that which Git was meant to handle, and
therefore consumes far more resources than a normal Git repository of its size.

And at the end they clearly mentioned that the repository access will not
enabled again.

P.S. : I was able to reach around 6,567,567 commits.

So this was my story how I used my mid semester exam frustration to do some
mischief with GitHub.

References :

[1]
[https://github.com/DefCon-007/Commiter-source](https://github.com/DefCon-007/Commiter-source)

[2][https://github.com/DefCon-007/Commiter](https://github.com/DefCon-007/Commiter)

* [Github](https://medium.com/tag/github?source=post)
* [Git](https://medium.com/tag/git?source=post)

### [Ayush Goyal](https://medium.com/@DefCon_007)

Open Source Enthusiast | GSoC’17 at OpenMRS

[OrkoHunter]

https://medium.com/kharagpur-open-source-society/using-git-bash-for-git-in-windows-d1876774fae3

# Using Git Bash for git in Windows

This blog post helps in installing git bash, for using git in windows. Git for
Windows provides a BASH emulation used to run Git from the command line. *NIX
users should feel right at home, as the BASH emulation behaves just like the
“git” command in LINUX and UNIX environments.

### Steps to install Git for Windows

1.  Click on the link to [[download](https://git-scm.com/downloads)]. This will
redirect to a page, where git will be automatically downloaded.

![](https://cdn-images-1.medium.com/max/800/1*r84LXjhlRvyL31uA9B0ULw.jpeg)
<span class="figcaption_hack">First window for installation</span>

![](https://cdn-images-1.medium.com/max/800/1*b_Gpwccl8Ju3cMIOdv2WrA.jpeg)
<span class="figcaption_hack">You can check off Git GUI, if you do not need it</span>

![](https://cdn-images-1.medium.com/max/800/1*Svkldsu4asg-CxUhuM-PWw.jpeg)
<span class="figcaption_hack">If you are having any preferable text editor, you can choose one.</span>

![](https://cdn-images-1.medium.com/max/800/1*D06k45WD3tmHG6Qc-AT9nQ.jpeg)
<span class="figcaption_hack">Choose option 1 , unless you know what you are doing</span>

![](https://cdn-images-1.medium.com/max/800/1*qtzvCVmTW1nv_cQdCJDdGw.jpeg)

![](https://cdn-images-1.medium.com/max/800/1*RSQfiZw7Gxtopd6JqMdDCg.jpeg)

![](https://cdn-images-1.medium.com/max/800/1*Y38aZdXgII6mHs7Q0FIR9g.jpeg)

![](https://cdn-images-1.medium.com/max/800/1*dsn3cGji9Y4HJDvLUWwsXA.jpeg)

![](https://cdn-images-1.medium.com/max/800/1*IPJen_NLY8WjxsAwS-eZrg.jpeg)
<span class="figcaption_hack">You can skip bleeding edge technology</span>

![](https://cdn-images-1.medium.com/max/800/1*0f20vDHE6R593r3D67anYw.jpeg)
<span class="figcaption_hack">Git is being installed</span>

![](https://cdn-images-1.medium.com/max/800/1*1vG0qWZ6ej92TWpa7SyvMw.jpeg)
<span class="figcaption_hack">Voila ! Git is installed</span>

### Some Steps before we start using Git

Note, we have to set username, and proxy settings, for using git in windows.

#### Configure git:

1.  After you’ve installed git properly, it’s time to set some variables for the git
configuration. You’ve to do this only once. Follow the commands on terminal.

2. User settings to be set —

     // Setting system.proxy in git                                               git config --global https.proxy 

3. Now check `git config --list` to know you've set the variables correctly.

Congratulations, you’ve git up and running on your computer. Now, it’s time to
start learning git.

* [Git](https://medium.com/tag/git?source=post)

### [Yash Sharma](https://medium.com/@yashrsharma44)

[OrkoHunter]

https://medium.com/kharagpur-open-source-society/installing-python-in-windows-ce059f644875

# Installing Python in Windows

This article deals with installing Python on Windows. Even though Python can be
installed in Windows, it is recommended to use Linux, to use Python and develop
applications. While I have used windows 10 for the demonstration of
installation, this can also be referred for installing the same in Windows 7.I
have installed both Python2 and Python3.

Let’s begin!

### Download the Python Software

Download the required files from the Python’s website
[[Python2](https://www.python.org/ftp/python/2.7.15/python-2.7.15.msi) |
[Python3](https://www.python.org/downloads/release/python-370/)].

### Installing Python 2

I have used the following steps to install Python 2

![](https://cdn-images-1.medium.com/max/800/1*UOiYWaNMJTgLIlIayw-OJQ.jpeg)
<span class="figcaption_hack">Choose Install for all users</span>

![](https://cdn-images-1.medium.com/max/800/1*en8i8Wf80eINFhv5n6Q1EQ.jpeg)
<span class="figcaption_hack">Keep the folder where Python will be installed in C drive</span>

<span class="figcaption_hack">Keep the default options, and click Next</span>

<span class="figcaption_hack">Python will be installed</span>

### Installing Python 3

After installing Python 2, we will install Python 3. Note that if you want to
install only Python 2( which is not recommended), then you have to append the
`python.exe` in the PATH variable.

<span class="figcaption_hack">Choose Add Python3.7 to PATH</span>

<span class="figcaption_hack">Python will be installed</span>

<span class="figcaption_hack">Python is installed.</span>

### Running Python 2 and Python 3

You can start Python 2, using `py -2` command in your command terminal. For
Python 3 use, `py -3`.

<span class="figcaption_hack">Python 2 and Python 3 is up and running !</span>

*****

### Caveat! Differences between Py2 and Py3

Note: This part is just for beginners who would be installing python for the
very first time. Of course, there are many more differences between the two
version.

* **print** : In python 2, the print was a statement, and hence one could print
any item, and wrapping them in curly brackets , was optional. However, due the
misuse of the above flexibility, the print statement was changed into a
function, and thus restricting the misuse of the above said advantage.
* **Integer division **: The integer division in python2 takes two numbers, and
returns the integer portion, as it discards the decimal part. This was certainly
not obvious, as `3/2` should return `1.5` and not `1`. Python 3 ensured that the
integer division returns values in float, rather than int.
* **Speed** : Python 3.3 performs at approximately the same speed as Python 2.7,
although some benchmarks measure the new language as being much faster.

* [Python](https://medium.com/tag/python?source=post)
* [Windows 10](https://medium.com/tag/windows-10?source=post)

### [Yash Sharma](https://medium.com/@yashrsharma44)

Open Source Enthusiast | IITian

### [Kharagpur Open Source
Society](https://medium.com/kharagpur-open-source-society?source=footer_card)

We are a group of Open Source Enthusiasts who focus on something more
preliminary and relevant, "A Love for Coding".

[OrkoHunter]

https://medium.com/kharagpur-open-source-society/git-cheatsheet-67ddd8cbbe94

# Git Cheatsheet

## What is Git?

![](https://cdn-images-1.medium.com/max/800/1*8xhLJt8Nlps8CDETPgO6lg.jpeg)

From [Git’s](https://git-scm.com/) official website:

Git is a [free and open source](https://git-scm.com/about/free-and-open-source)
distributed version control system designed to handle everything from small to
very large projects with speed and efficiency.

**About Version Control**

What is version control, and why should you care? Version control is a system
that records changes to a file or set of files over time so that you can recall
specific versions later. Even though examples in most of the cases show software
source code as the files under version control, in reality any type of file on a
computer can be placed under version control.

**To install Git:**

`sudo apt-get install git`

**To check version:**

`git -- version`

**For configuring:**

`git config -- global <keyword> “Data”`

* `<keyword>` can be `user.name` ,`user.email`, `core.editor` etc.
* To display current saved configration type `git config --list`

**For help:**

`git help <verb>`

eg: `git help config `for help regarding configration process

**Creating a local repository:**

* Simply cd into the directory you want to track and simply type `git init`. This
will create a .git file in the directory with a basic skeleton without any
commits.

**To check which files can be commited:**

`git status`

this will list the files that can be commited

* To ignore files create a .gitignore file using `touch .gitignore`
* Open this using text editor and add names of files you want to ignore

**Moving files to staging area:**

* For adding files individually use –`git add <filename>`
* For adding all files at once use –`git add -A`
* To remove files from staging area use –`git reset <filename>`and to remove all
simply type `git reset`

**To commit the files:**

`git commit`

but it is necessary to add messages with the commit to make sure what we did ;
so for that we use `-m` extension like `git commit -m “message”`

![](https://cdn-images-1.medium.com/max/800/1*fwUZtFBXFvHwMwmAWlde5w.png)
<span class="figcaption_hack">Staging and committing Flowchart.</span>

**To check the commit history:**

`git log`

**Cloning a repository from internet:**

`git clone <url> <location>`

* To clone into current directory use `.`in place of location.
* To check status of the cloned repository use `git remote -v` This will give the
location from where it is fetched.
* `git branch -a` gives all the branches in the cloned repository.

**Changing and submitting:**

* Make changes to the file of the cloned repository.Now to see change made type
`git diff <commit>`

This will display the change made with respect to the` <commit>`. By default if
`<commit>` field is left empty , Git compares it with` HEAD` i.e the last
commit.

> Another feature or form of git diff is

> `git diff --cached <commit>`

> This shows the diff between your **staged changes **and the <commit>. So, here
> it gives the diff between your index and the last commit.

> `git diff <commit>` shows the diff between the *current ***working tree **and
> the <commit>.

* Now `git status`will view the modified files .
* Add the file to the staging area using `git add -A.`
* Commit these files with appropriate message .
* Now before pushing it back . We need to pull and check whether any other person
made a change in the branch since the last time type in `git pull origin master`
( If on master branch else use branch name in place of master).

> **IMPORTANT NOTE:**

> `git pull` is often confused with `git fetch` .The basic difference is stated
> below.

> `git fetch` really only downloads new data from a remote repository — but it
> doesn’t integrate any of this new data into your working files. Fetch is great
for getting a fresh view on all the things that happened in a remote
repository.<br> Due to it’s “harmless” nature, you can rest assured: fetch will
never manipulate, destroy, or screw up anything.`git fetch`* *is also useful
when we manually wish to merge or check and merge conflicts that arise whereas
`git pull`* *directly fetches and merges (refer branching for merge). It is
therefore more preferred to use `git fetch`* .*

> `git pull` in contrast, is used with a different goal in mind: to update your
> current HEAD branch with the latest changes from the remote server. This means
that pull not only downloads new data; it also directly **integrates** it into
your current working copy files.

Now for finally pushing type in –>

`git push origin master`

![](https://cdn-images-1.medium.com/max/800/1*lWS_YsYDgGNzwleoSK8jOg.png)
<span class="figcaption_hack">Basic process Flowchart.</span>

**Branching:**

![](https://cdn-images-1.medium.com/max/800/1*roh6Eb2dFSeQhM0Fgs0cng.png)
<span class="figcaption_hack">A typical image which represents blue dots as master and rest as side branches.</span>

* To create a new branch use `git branch <branchname>`
* To check all the branches present use `git branch`
* To switch over branch use `git checkout <branchname>`
* To push a commited changes type in `git push -u origin <branchname>`
* To merge the current branch you are working on to master use `git merge
<branchname>`
* To push the changes we simply use `git push origin master`
* To check it they are merged type in `git branch --merged`
* If the branch is successfully merged we can now delete the branch–`git branch -d
<branchname>`

**To switch to a previous version of the code:**

We do `git reset <mode> <SOME-COMMIT>`(some commit is the commit number ) then
Git will:

* Make your current branch (typically `master`) back to point at `<SOME-COMMIT>`.
* Then it will modify your working tree and the index (“staging area”) according
to the `<mode>` selected.
* The mode must be one of the following (If `<mode>` is left blank then by default
`--mixed` is selected) —
* `--soft `—Does not touch the index file or the working tree at all (but resets
the head to` <SOME-COMMIT>`, just like all modes do). This leaves all your
changed files “Changes to be committed”, as *git status* would put it.
* `--mixed `— Resets the index but not the working tree (i.e. the changed files
are preserved but not marked for commit) and reports what has not been updated.
This is the default action.
* `--hard `— Resets the index and working tree. Any changes to tracked files in
the working tree since `<SOME-COMMIT>` are discarded.

**Stashing**

Often there is a condition where code is in a messy state and you don’t want to
work any further . Also you can’t commit this *half-written code*. In such
conditions function called `git stash` is used.

* Type in `git stash` this will push this code onto a stack while keeping the
working directory clean.Further use of this function again and again on the same
code will generate a stash stack.
* To display the stash stack use `git stash list` .The list will be numbered as
`stash@{0}`,`stash@{1}` ….`stash@{n}` .
* Finally when you decide to work again and want to apply the changes use `git
stash apply` . To apply any older stash from the stash stack use `git stash
apply stash@{n}` where n is the stash number.

**For Reference regarding Git :**

* For practicing and learning git checkout —
[https://github.com/kossiitkgp/git-sandbox](https://github.com/kossiitkgp/git-sandbox)
* Basic git
:[https://www.youtube.com/watch?v=HVsySz-h9r4&t=464s](https://www.youtube.com/watch?v=HVsySz-h9r4&t=464s)
* Resolving a pull request:
[https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/](https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/)

* [Git](https://medium.com/tag/git?source=post)

### [Taapas Agrawal](https://medium.com/@taapasagrawal)

[OrkoHunter]

https://medium.com/kharagpur-open-source-society/virtual-box-and-vagrant-2eaa87be7772

# Learning command line basics and Virtual box

Hello people!

So I was looking up for a course that would teach me the basics of linux command
line and I got across this one. Though I already know the basics of command line
but just in case I was missing something, I thought to go through it once.

https://in.udacity.com/course/linux-command-line-basics--ud595

This course is for a beginner. It’s not preferred to go through it, if you
already know about the commands. But I have mentioned the brief summary of it
and key points which I didn’t know.

In the start of the course, I found something really fascinating, how to set up
a virtual machine on my own computer. It made me feel really good that I can set
up a new computer on my own system. Sounds interesting, right? Why Virtual
Machine? This link will tell you the reasons why people prefer to use the
virtual machine for their work.

So in this blog, I will mention all those things which I learnt something new
today.

1.  To set up the virtual machine, follow the above link. In the first few slides,
you will be carried through the instructions how to set the virtual environment
up. I wont mention that here.
1.  `cat <file_name>` will display the content of the file on the terminal itself.
1.  `man <command_name>` for eg: man apt will give you the manual pages (detailed
help) of the command apt. you can look through it in case of a doubt. *Note*:
Many commands also have a `-h` flag which shows help. `man` shows a “detailed
version” of the help.
1.  Line based commands: There some commands which when typed doesn’t return back
the cursor, eg: `bc` (used to access the calculator). You got to type quit or
Ctrl+D for exiting from that interface.
1.  There is a command `less <file_name>` which is used to access a text file page
wise rather than using `cat <file_name>` which displays the whole text. This is
especially useful when dealing with long texts.

<span class="figcaption_hack">Relative Path v/s Absolute Path</span>

6. `cd` without arguments is a shortcut to take you to your home directory.

7. `mkdir` is used to make a directory (You all must be knowing that). But
`rmdir`is used to remove an empty directory (Note empty). If you wish to remove
a directory with files in it, you will have to do that recursively using `rm -r
<directory name>`*.*

8. `ls` is used to list all the files in the current directory. `ls -a` will
list all the hidden and non-hidden files in the directory and `ls -al` will give
all the details of the files. Here -a and -al are called the flags.

9. `touch` will create an empty file in the current directory.

10. `cp` copies the file in the required directory. Syntax is like `cp test.txt
Downloads` . Here the second word is the destination folder. `cp -r docs
more_docs` copies the content of of docs to more_docs. Note the -r flag standing
for recursive.

11. `date` gives the current date.

So to wrap up, using the virtual machine really amazed me. Using it, I can store
files hidden, in case needed. I even learnt about some new commands of the
command line.

Keep learning! Cheers!

* [Terminal](https://medium.com/tag/terminal?source=post)
* [Vagrant](https://medium.com/tag/vagrant?source=post)
* [Virtual Machine](https://medium.com/tag/virtual-machine?source=post)

### [Nikhil Choudhary](https://medium.com/@nikhilchoudhary_17565)

[OrkoHunter]

https://medium.com/kharagpur-open-source-society/an-informal-introduction-to-kwoc-62fc5e686f79

# An informal introduction to [KWoC](http://kwoc.kossiitkgp.in/)

**Great People of tomorrow, every perfume starts with one ingredient but it is
the last one that makes it come to life.**

Hi! and Welcome! To all esteemed student who are trying to pursue their dreams
irrespective of their departments and previous experience.

Everyone is welcome. Here “Everyone” is not a metaphor, “Everyone” means
everyone.

Open source is not just “GSoC”. It is a lot about, idea, ego, altruism,
expression and satisfaction. From software to hardware to information anything
can be opensource. We do open-source because we love to. “GSoC” is just a good
motivation to start.

Some famous open source projects:

Firefox, Linux, Ubuntu, VLC.

**Now coming back to KWoC**, common problems faced and how to be prepared.

**Psychological Barriers** :- Completing KWoC requires you to overcome a
statement “I have just started with coding” or “These are State of Art things,It
requires a lot of experience”. I will easily term these statements as myths or
excuse.

**Why these thoughts arise**?

From project info. You will read fancy terms as “Scraping” “Audio-recognition”
“Natural Language Processing” “Deep Learning” “Networking” and you will lose
your heart. But the matter of truth is that project info tells you just about
what that project really does, not about the process how it performs that task.
In most of the projects mentioned, you are not going to implement everything
yourself and you don’t need to read everything present in the codebase. There
are pre-implemented library for most of state of art things, you just need to
learn some basic info about how to use these libraries.

Most of the software development is based on basic conditional statements,
libraries and lot of common sense.

**Mentor Problem:**- A lot of time there is a problem in response of mentor. A
lot of time mentor doesn’t respond in a helpful way or doesn’t respond at all.
Let me tell you a ravishing truth “This phenomenon happens in GSoC as well”.
Really you can’t help. Now what, you are in shoes of Robert frost, “Two roads
diverged in a yellow wood, And sorry I could not travel both”, either you can
become hopeless again and take a road more traveled or you can make it a
memorable event where you overcame your mediocrity. Try some other project with
similar portfolio. The cycle is shortlist project, talk to mentor, if you find
him convincing or if you think you can do project without his guidance then only
proceed, then code debug and repeat.Bug co-ordinator, but mark my word if you
are bugging anyone it’s your responsibility to respect his/her time, give back
your effort or remember that “Karma is a bitch”.

**Ubuntu:-**If you are new to ubuntu, “KWOC is going to be really awesome” .
Because you will remember this winter for like 1–2 years, because if you are
high on grit you will be going through a lot of learning shit. Okay, Siri is
here to your rescue, Ubuntu is nothing like Windows but considering you as a
Windows user, Instead of .exe there are other methods to install applications.

![](https://cdn-images-1.medium.com/max/600/0*7IlL4k_OFlZhgC3u.)
<span class="figcaption_hack">Here is some Chinese wisdom for you my friend.</span>

There is terminal in ubuntu **(ctrl + alt + t)**. Here is an important
**[**[link](https://www.pcsteps.com/5010-basic-linux-commands-terminal/)**]** to
make you little aware of terminal. Get aware of this blog, terminal is quite
important for software development. Here is the
**[**[chest]](https://ubuntuforums.org/showthread.php?t=801404) of all beginner
friendly links.How to install software and
libraries**[**[link](https://askubuntu.com/questions/307280/how-do-i-install-applications-in-ubuntu)**]**.
You don’t need to learn everything at one go. As you start coding and setting up
environment for your respective project refer to these link as per need. If you
have not installed Ubuntu then visit this
**[l**[ink](https://wiki.metakgp.org/w/How_to_install_Ubuntu_as_Dual_Boot)**]**.

**Git:-** A command line tool to save different versions of your code wrt to
changes. Nothing more or less than that. People have complicated this
unnecessarily. It also interacts with Github and Bitbucket.

One of the best places to learn git is [Learn Git
Branching](http://learngitbranching.js.org/)

Starter pack of git :-

a) If you have installed Ubuntu very recently then for installation of git

    sudo apt update && sudo apt install git

b) When you use git for the first time, you’ll have to configure it with details
matching with your GitHub profile.

    git config — global user.name “
    ”

    git config — global user.email “
    ”

c) If you are behind a proxy server then to configure git to access Github.

    git config — global http.proxy 172.16.2.30:8080 

d) Then login in your Github account.

**This is just a sample. Change URL according to your project. Don’t just
blindly copy paste. Read instruction properly.**

e) Visit this link [Kossiitkgp website
repo](https://github.com/kossiitkgp/kossiitkgp.github.io) [Visit your respective
project link].

f) On top right of that window click on watch button and pick watching option

g) Beside that button is star, star it as well, then there is fork button, click
on fork button.

h) Then you will be automatically directed to your forked window.

k) Click on that green button of clone or download.

l) When you click there, a menu appears where there is an option to copy link
but ensure that you copy the link is in this format

![](https://cdn-images-1.medium.com/max/800/0*bzxLympOO7EubZJW.)

And not in this format:

![](https://cdn-images-1.medium.com/max/800/0*NuKuoB2gB1FnM4af.)

m) Then press ctrl+alt+t

n)Then enter in terminal “git clone ” and then press ctrl+shift + v and then hit
enter (hitting enter is an untold rule).

    git clone 

o) cd kossiitkgp.github.io **[change according to name of your project]**

p) Then enter in terminal git remote add upstream and then press ctrl+shift+v

    git checkout -b newbranch

r) If you can, edit some files in cloned folder (using git clone)for productive
use, save your changes by ctrl + s (if using sublime or gedit etc) .

s) Then properly review your changes then type this command in terminal in
already opened terminal.

    git add -A

    git commit -m “
    ”

    git push origin 

v) Enter your username and password. While entering password you will not see
anything

w) Done

x) Then visit
[https://github.com/your-user-name](https://github.com/yourusername)**(plz
change)**/kossiitkgp.github.io

y) Then click on pull request then click on create new pr.(Check two branches
which you are comparing)

![](https://cdn-images-1.medium.com/max/800/0*26RvHxhcjsbA4ZSJ.)

![](https://cdn-images-1.medium.com/max/800/0*nfM7sqVODhn2qA30.)

![](https://cdn-images-1.medium.com/max/800/0*xixf1SOFoTSCeN98.)

z) If you are sending pr after few days of cloning then before **git push**
first do

    git pull 

**(there are other methods as well like fetch and rebase) **or face the wrath of
merge conflict.

For proper crisp tutorial read
[[this]](https://www.atlassian.com/git/tutorials).

**Github:-** It is just a website(like Fb/Orkut) where pull request are similar
to Fb’s friend request. It is definitely more productive and useful.

But a more complicated definition

*“GitHub is a web-based Git or version control repository and Internet hosting
service. It is mostly used for code. It offers all of the distributed version
control and source code management (SCM) functionality of Git as well as adding
its own features. It provides access control and several collaboration features
such as bug tracking, feature requests, task management, and wikis for every
project.”*

Definitely, it gives a lot more insight only if you understand the terminology
:) :)

**Reading codebase**:- My steps would be:

**A)**

*1. Setup a source insight( or any good source code browser you use)
workspace/project with all the source, header files, in the code base. Browsing
at a higher level from the top most function(main) to lowermost function. During
this code browsing, keep making notes on a paper/or a word document tracing the
flow of the function calls. Do not get into function implementation
nitti-gritties in this step, keep that for a later iterations. In this step keep
track of what arguments are passed on to functions, return values, how the
arguments that are passed to functions are initialized how the value of those
arguments set modified, how the return values are used ?*

*2. After one iteration of step 1, after which you have some level of
understanding of code and data structures used in the code base, setup
a…………………..*[[source]](https://stackoverflow.com/questions/214605/the-best-way-to-familiarize-yourself-with-an-inherited-codebase)

**B)**

1) Identify why I’m reading code. Could be to understand an algorithm, see
different coding style, learn a language, find a defect, figure out a
workaround, understand a badly documented feature, know how to extend a feature,
make a plugin, discover how to exploit a feature beyond the initial intents, …

2) Find where to start reading. That could be the main/index file of the
application or library, a manifest. Or you could search the code for a
documented
feature……………….[[source]](https://www.quora.com/How-do-you-read-a-big-code-base-like-a-pro)

**Googling:-** Google any error which comes while development.This
[[URL]](https://medium.com/@apoorvakumar169/art-of-searching-the-web-for-soft-dev-1-4e7044c6f95f)
is in different context though. But you can get some idea. If you face any
problem while development just translate your problem to words and search, if
you are not getting solution reframe your problem and then search again. Before
asking anyone perform the above instruction at least two times.

**Learning:-** Learn what you google. If you are just googling and not learning
you are equally dependent as you were before. Here learning refers to mugging.

**Libraries:-**This is the basic difference b/w Windows and Ubuntu , In Windows,
we install whole everything to do something but in Ubuntu, we install something
to do a lot of thing. A minimalistic approach towards development.

As one of the member of open-source community, I would like you to introduce to
its manifesto

*We need to take information, wherever it is stored, make our copies and share
them with the world. We need to take stuff that’s out of copyright and add it to
the archive. We need to buy secret databases and put them on the Web. We need to
download scientific journals and upload them to file sharing networks. We need
to fight
for……….*[[source]](https://en.wikisource.org/wiki/Guerilla_Open_Access_Manifesto)

*Collective intelligence — multinational, multiagency, multidisciplinary,
multidomain information-sharing and sense-making — is the only means of
obtaining near-real time understanding of complex systems sufficient to achieve
resilience in the face of changes. Many of these changes, including biospheric
ones such as climate change and depletion of planetary resources, are the result
of human activity and industry in the last three
centuries.*[[source]](http://realitysandwich.com/151036/open_source_everything_manifesto/)

In a more beautiful way

**“Beneath the mask, there is more than flesh, there is an idea and ideas are
bulletproof”**

With Love From:

**Kharagpur Open Source Society**

* [Git](https://medium.com/tag/git?source=post)
* [Open Source](https://medium.com/tag/open-source?source=post)
* [Pull Request](https://medium.com/tag/pull-request?source=post)

### [Apoorva Kumar](https://medium.com/@apoorvakumar169)

[OrkoHunter]

https://medium.com/kharagpur-open-source-society/writing-kickass-readmes-8857fbe03515

# Writing Kickass READMEs

Writing documentation for code is **extremely** important. Alas! I realized this
late. Nevertheless, you should not make this mistake again.

This is written with respect to software related READMEs, if you want guidelines
for other stuff, then probably this isn’t the right place.

Let’s discuss the potential problems of not having a good README:

### Not a clear description of the project

I don’t recount how many times this has happened with me. I usually just scroll
through all of my friends’ projects on GitHub to see what they are upto these
days and time and again I have been disappointed by not seeing a good
description about the project and it is too time consuming to read the whole
source code to find out what that repository is actually doing.

In fact some professional projects too have vague description and you are left
clueless as to what the code does. Sometimes the project is so big that they
can’t really mention all of it in one thing. That is the time you should
probably split it in many repositories or folders (if you desperately want a big
mono repo like Google) and each folder should contain some high-level
information of what the code inside it will do, just like recursive `Makefiles`.

### Not having a installation guide (or an incomplete one)

So since you have got the viewer interested in trying our your software by
writing a good introduction, you would now probably piss off her by sucking at
writing an installation guide.

What a developer should understand is that since your development environment is
setup to run that code, doesn’t mean everybody’s is. One should always write the
whole installation process for all systems that the software supports and it
should clearly mention that the software doesn’t really have support for this
system but it would be great to support it in future or something.

For unix-based systems, one should list out all the ways to install the
software. Let’s take an example of Ubuntu. If you have managed to get your
software packaged with a `.deb` file and also uploaded it upstream so that it
can be used with `apt-get`, then that’s just awesome!

Sometimes you might be releasing it and then packing the source code in a
`tar.gz` format, still awesome. In the latter case, it would be worth while to
mention all of the dependencies required. Also, just the name isn’t enough,
their exact version numbers is even better because you might never know when a
python code breaks because of the version bump because well that’s how things
work in python world.

If you are expecting the user to do a `gcc` based compiling for each source code
file then God just forgive you. It is time to move on to at least `Makefiles` to
automate that process for you.

If something doesn’t work in particular systems, it is **important** to list it
out.

### No User Documentation

You don’t have a user documentation? Well then how do you expect others to use
your software. User documentation should be in another file or folder (if it is
quite big) and should probably be in some kind of a format which can be rendered
easily. You can either write it in markdown format or in Github wiki’s so that
it can be easily read on GitHub or you can write in `man` pages form for the
oldies to read it. But you should have it. And that’s not it, your README should
explicitly point out to the documentation and also tell the user how to access
it and actually read it.

Also you can include the very basic use case in the README itself.

### No guide for people to actually contribute

If you have the viewer till now and she is thinking of actually contributing to
your project, then kudos, your project is **awesome**.

A very important part of the contributing guide is to setup the development
environment. Again in this, it is worthwhile to get into the platform specific
information. For eg. Windows will have different development environment while
Ubuntu will have a different one. You should mention what IDE you used or the
tools that you used.

Now your project might have some development related dependencies. You should
mention about that too. Now finally the viewer can have successful environment
setup to actually contribute to your code.

Now, you might be following some conventions for writing your code, right? It is
worth while to mention the conventions that you have followed in a separate file
and link it in the README.

Then you would have a specific way or two in which you accept others’ code,
right? You might be using Github’s Pull Request based system or the age old
sending patches via email using `git-format-patch` and `git-send-email` just
like old times. Whichever you prefer, it is important to specify this in a new
file possibly named as `CONTRIBUTING GUIDELINES` or something. If you have any
specifics about the project **mention** it there. Don’t just expect people to
know it by default.

It is also worth while to link the `easy to fix` bugs for new comers so that
they can get familiar with the code base without trying to mingle with the core
parts of the software.

### No technical documentation

If you are having a big project, then you might be having a “core” part which is
used by other parts of code. Have you documented it? Or you just expect people
to `git-grep` and `git-blame` to find the relevant use cases, definition of the
functions and the documentation inside the commit messages? If you are doing
that, it is not exactly bad (I understand you might be having your own reasons)
but it is good to write a technical documentation wherein you will tell the
programmer what a method does and how to use it. This will also make sure she
doesn’t write a method to do the same stuff again and thus it would reduce your
redundancy.

### No mention of how to run tests

Of course you project has tests, otherwise how can you make sure that by writing
new code, you don’t break the old code? Your README should contain how to run
the test suite. There are tons of different test suites available in the market
and it is time consuming for people to check out your test framework and make
guesses as how one could probably run it. You should mention how to run
individual tests, the whole test suite, and how to skip some tests, and if your
test suite framework doesn’t support all of these features, then maybe the one
you are using should be replaced.

### No license

Yes, legal matters are important too! Whether you are releasing it as an truly
open-sourced software with `BSD` license or something else, you should mention
it. If you don’t realize the importance of licensing, that is maybe because your
project isn’t big enough. Once a lot of people read your code, use it, they
might try to finger with it whether you like it or not. You should explicitly
specify “how much fingering” you can tolerate in a separate file named as
`LICENCE` in full detail like a legal document and if you are using a popular
license, you can just mention the name in the README.

### No place to mention about bugs

You don’t have a bug management system? Okay, I agree this isn’t really always
required but if you do, you should explicitly mention and link to that. If you
talk about bugs in GitHub issues, then mention it there. Also if you are using
GitHub, use labels to specify the bugs. If you still track bugs using emails via
mailing list, specify that too also include a link to the old archives of the
mailing list.

### No mention about the version control system

Well if you are seeing the project on Github, is it wrong to assume that it uses
`git`? Yes, there are many projects that I know use multiple version control
systems and the best example is `nmap`. They accept patches (and PRs) in all
forms and integrate it together. So explicitly mention about all the version
control systems that you would be using and how you would accept foreign code
for each.

### No contacts

How should the viewer contact you in case he needs something or has something
for you? Probably now you have a good incentive to give out your contact
information (mainly email is good) for others to contact you or just say “Thanks
for the awesome software!”.

### No fancy GUI pictures

You probably would have spent a hell lot of time in designing and tweaking the
GUI and were frustrated when a font size looks bigger than it should, so you
should show it off. There are lots of people who like the fancy GUI way of
software rather than the good old black terminal with green text. If you have a
fancy GUI, try and put the pictures of it in the README. GitHub’s markdown
renders it, but I don’t think `man` pages do. But if you **really** care about
man pages, you probably won’t even have cared enough to make a fancy GUI.

### No table of contents

Well if you try to write everything that I have pointed out, then it is probably
good for you to follow this advice too. Have a `Table of Contents`. This way,
the README will look more organized and it would make reading much easier.

Okay, now that I have ranted a lot, I hope you know **How to Write KickAss
READMEs**.

*****

This [article](http://www.bauva.com/blog/Writing-Kickass-READMEs/) originally
appeared in Pranit Bauva’s [website](http://www.bauva.com/).

* [Github](https://medium.com/tag/github?source=post)
* [Documentation](https://medium.com/tag/documentation?source=post)
* [Software Development](https://medium.com/tag/software-development?source=post)
* [Software](https://medium.com/tag/software?source=post)

### [Pranit Bauva](https://medium.com/@pranit.bauva)

[OrkoHunter]

It's done!