Prerequisite : Making your first Open Source Pull Request | Github If you are new to open source and want to contribute to it, you must have read tens of different articles on how beginners can get started with open source and you still haven’t made a single contribution to any open source organization and you are still as intimidated by it as you were when you had first started reading such articles. If you can relate to anything that has been mentioned above then you should read this article.
Why you should read this article?
Before I start I want to tell you that I was in the same situation some time before and this article is not going to be one of those generic articles. This article is particularly about one organization called DuckDuckHack which in my view is the best for beginners to start with and hopefully within a few hours of finishing this article you would have documented and submitted your first Pull Request.
The Organization
DuckDuckHack is an open source community dedicated to the development of DuckDuckGo. DuckDuckGo is an Internet search engine that emphasizes protecting searchers’ privacy and avoiding the filter bubble of personalized search results. It does not profile its users and shows all users the same search results for a given search string instead of creating personalized search results for every user. The emphasis is on returning best search results.
The Mission
The DuckDuckHack community is on a mission to make DuckDuckGo the best search engine out there and the community needs help. Help can be in the form of Instant Answers(or IAs). For example a GCD calculator a user enters 2 numbers and the string “gcd” along with it and instead of going to another site to find the answer they get the answer right there on DuckDuckGo.
Types of IAs:
According to DuckDuckHack Docs there are four types of IAs
- Goodies
- Spice
- Fathead
- Longtail
We are going to focus on goodies IAs since the rest are API based and might not be suited for beginners. The easiest kind of goodie is a cheat sheet. For example you want to a quick c++ reference, then all you have to do is to go to DuckDuckGo and type the following “c++ cheat sheet” and search. It will look like the following. A cheat sheet can be about anything from movies & video game cheat codes to a linux distros cheat sheet all you need is an idea and the rest is simple.
Getting Started
This section is written under the assumption that you are familiar with git and github if not then you should probably check out this link.
Setting up your development environment :
- Go to GitHub and fork duckduckgo/zeroclickinfo-goodies. That’s the main repository containing the goodie IAs which also include cheat sheet
- Now you have a copy of their repository on your github profile and this fork will be your origin while the main repository that you have forked will be your upstream(these terms will be explained later)
- Instead of cloning this repository onto your computer, we will use an online development environment called codio
- Signup on codio or just signup using your github account
- Join the DuckDuckGo organization. Codio is free for DuckDuckHack community members.
- Now go to this link and fork the project on your codio profile by clicking on the projects tab and selecting the fork option.
- Now a popup window appears select “Box & Project” option.
- Now clone your github fork (origin) onto your codio by first going to codio projects page and selecting “DuckDuckGo” project
- Now open Tools->Terminal type
git clone .git (your github URL is your fork on github)
- Enter your github credentials and press enter
Now you will have the file tree of the github fork and you can view all the files. Now we will move on to the contribution part.
Making your contribution
Before starting with editing existing or creating new files we need to set up our remotes so that we can pull and push changes to and from codio. Setting up remotes:
- Change into the working directory by executing the following command in the terminal
cd zeroclickinfo-goodies
- Add your first remote to the main DuckDuckGo repository on GitHub by doing
git remote add upstream https://github.com/duckduckgo/zeroclickinfo-goodies.git
- Since you have already cloned your GitHub fork onto your codio machine it already has an origin remote set to your GitHub fork or you can still do this to be sure
git remote add origin https://github.com/your_username/zeroclickinfo-goodies.git
Before writing the cheat sheet you need to go to the IAs page sign in with your GitHub account and make a new IA page under the name same as that of your cheat sheet for example I wrote a lolcode cheat sheet as my first contribution so I named the IA page Lolcode Cheat Sheet and I added the description and the source description. The source was just a website where I found the basic information about Lolcode keywords and escape sequences and the rest was just copy paste.
Writing the cheat sheet
A duckduckgo cheat sheet is just a single json file in which the information is stored in the form of key-value pairs. All the cheat sheets are stored in
zeroclickinfo-goodies/share/goodie/cheat_sheets/json
. So continuing with my example of lolcode cheat sheet lets get down to writing it.
- After making the IA page you need to go back to codio.com and open the terminal and change into your working directory
cd zeroclickinfo-goodies
- Before making any contribution you should make your own branch in which will later be merged with the master branch of the upstream repository. For that do the following
git checkout -b lolcode
- your branch name could be anything but since I am using my example so I’ve used lolcode. Remember always to create a new branch and never to make changes in the master branch or you might end up upsetting a lot of people.
- Now we will generate the boilerplate json file by doing the following:
duckpan new --cheatsheet.
- It will prompt you for a name and you will type the name and hit enter. For example lets name the cheat sheet lolcode and hit enter. You will see in the file tree that there is a new json file by the name lolcode.json
- Click your boilerplate file and it will open in a new tab, now you can start editing it.
- As you can see most of the work has already been done for you all you need to do is edit some strings. Start by adding metadata
"id": "lolcode_cheat_sheet",
"name": "lolcode",
"description": "lolcode keywords and how to use them",
"metadata": {
"sourceName": "Esolang wiki",
"sourceUrl": "http://www.your-source-url/"
},- Now fill in the aliases. These are the search strings that the user will look for example if I search for “cpp cheatsheet” or “c++ cheatsheet” cpp and c++ are the aliases and cheatsheet is the trigger. for example for lolcode cheat sheet we will have only 1 aliases.
"aliases": [
"lolcode"
],- Choose the code template if you are going to make a programming cheat sheet
- Now we fill out the different sections the information will be filled out in the form of key value pairs lets say I have a data types section for my lolcode cheat sheet and I want to present a data type with its definition then the data type will be the “key” and definition will be the “value” and the section name will be data type
"sections": {
"Data Types": [
{
"val": "It is an integer",
"key": "NUMBER"
}, {
"val": "It is a float",
"key": "NUMBER"
}
]
}
- You will also have to give a section order such as
"section_order": ["Data Types", "Escape Sequences"]
Validating the cheat sheet
You can validate your json by using the JSON Validator and copy pasting your JSON in the validator. Now validate your cheat sheet code using the following command in the terminal
duckpan test CheatSheets
If you get no warnings that means your cheat sheet is OK. Testing your cheat sheet
- Go to the terminal and type
cd zeroclickinfo-goodies
- Now type
duckpan server
- and press enter
- Now click the DuckPAN Server button on the top of the screen which will open a new browser tab with DuckDuckGo homepage
- Now search for your cheat sheet for example lolcode cheat sheet and you will see something like this.
Pushing your changes
Now you need to commit and push your changes to your fork.
- Go back to codio and check if you are still in your working directory zeroclickinfo-goodies
- Now add and commit all the changed files by doing
git add
- press enter
git commit -m "Description of your changes"
- press enter
- Now push your changes to your GitHub fork by doing
git push origin branch_name
- You will be prompted for your GitHub username and password once you enter those your fork will be updated.
Drafting your pull request
- Go to your GitHub fork and check if your cheat sheet has been updated or not. If yes, then you are ready to make your pull request
- Click the green “New pull request” button
- Review the changes and click “Create Pull Request”
- Enter a title and description for your pull request along with the IA page link for example “New Lolcode Cheat Sheet”
- Finally click create pull request
Conclusion
If you’ve successfully the above steps, then congratulations you just made your first open source contribution. Now you must keep something in mind, cheat sheets are the lowest priority tasks and might take months to merge so you will have to wait.