Working with Git
One thing we love about DuckDuckHack is that it's frequently people's first open-source contribution. If that's the case for you, you might be encountering Git for the first time. Git is a tool that allows many people to collaborate on one codebase.
At DuckDuckHack, we have several Git repositories (hosted on GitHub.com), which reflect the current state of Instant Answer code. The Instant Answers that run on DuckDuckGo.com come directly from these repositories.
The two main repositories are Goodies and Spice. There's no particular reason to divide it this way, except that Goodies don't make external requests, and Spice Instant Answers do.
The following is an overview of how you'll use Git to contribute to DuckDuckHack. This is the workflow used by all of our contributors worldwide to collaborate on Instant Answers.
Step 1: Fork the Repository
Your ultimate goal is to add code to the Spice repository, in this case. To do that, you'll first make a copy that you can freely modify. That's called "forking a repository".
(Find out how to do this under setting up your development environment.)
Step 2: Clone Your Fork of the Repository
Forking on GitHub means you've made a copy up on your GitHub account. However, to edit files, you'll need to clone that fork to a machine you can access. In our case, that will be your Codio environment.
(Find out how to do this under setting up your development environment.)
Step 3: Create a Working Branch for Coding
Inside your repository, Git allows you to work on parallel versions of your code. These are called "branches."). You can also think of a branch is an "independent line of development."
Every repository starts with one, default branch called master. It's best to keep master clean of changes, and instead work off of new branches. This allows you to keep master updated with the original repo.
Make a new branch by typing:
git checkout -b my-new-branch
This will create a new branch and also switch into it.
You can switch back to master by typing:
git checkout master
and back to your new branch the same way.
Keep a separate working branch for each Instant Answer you're working on. This allows you to keep the changes separate. That way any hold-ups on one Instant Answer won't delay acceptance of another.
Step 4: Make Your Changes
Add your new Instant Answer to the repository, test it, and play around. Or, make changes to an existing Instant Answer. This is the fun part!
Make sure to commit your changes along the way. "Committing" is the most important action in Git. It's like saving a snapshot of your project at various milestones. You should commit often, to mark units of achievement - however small!
Committing involves both the git add and git commit commands. We recommend this great tutorial on how to use both.
Step 5: Update master with the original repo
While you're working, many other developers around the world have been busy merging changes to the original repository. Most likely there won't be overlap, but there may be some merge conflicts if two people have made changes to the same Instant Answer.
It's best practice to start each work session by updating your fork with the latest changes. This is one major reason we kept master free of changes. We can use it as an ongoing reflection of the original repository's master branch.
To update your master branch, git checkout the branch, and type:
git pull upstream master
This will pull the changes from the latest master branch into yours, so you’re up-to-date. (GitHub has a slightly more detailed, and equivalent, set of instructions.)
Next, to update your working branches off of master, merge or rebase with the master branch.
If you encounter any merge conflicts, don't sweat: GitHub has a great guide for how to resolve them.
Step 6: Make a Pull Request
Ready to submit your work? It's time to make a pull request on the original repository.
A pull request is the process of submitting changes to a collaborative project. It's your way of asking that the changes made on your fork be incorporated into the original repository.
Because we're focusing on Git, we'll gloss over the guidelines for making a pull request. If you're working on a real Instant Answer, you'll want to learn more about the process for going live.
The first step to making a pull request is updating the clone of your repository that lives up on GitHub.com. Go to the branch you're working on, and type:
git push origin my-branch-name
This updates the equivalent branch on GitHub.com. Next, visit your repository on GitHub.com. Find the branch you just pushed. Finally, click the Pull Request button. GitHub has excellent instructions on how to do this on their site.
Step 7: Update Your Pull Request
Once created, your pull request page will be the center of feedback and discussion of your changes. You can continue to make ongoing changes to your pull request. Simply keep making commits - and push them your fork on Github - and the pull request will update automatically. (This is another reason it's critical to keep contributions separate on different branches: it keeps pull requests clean of unrelated changes.)
Have questions about git? Talk to us on Slack