Blog logoThe Open Source U

git

A distributed version control system commonly used in the open source world.


Using git to Contribute to OSS

 •  Filed under OSS, oss-concepts, GitHub, git

There are plenty of resources out there to learn how to use git... but I'd say a good percentage of those focus on using git from git init and on -- that is, starting a new repository from scratch.

This post is going to focus on using git to contribute to an existing, established project on github. I'm assuming no prior knowledge of git/GitKraken/SourceTree. That said, I'm going to assume you are using at least GitKraken or SourceTree and not the CLI.

Example Project

I encourage you to follow along. For my screenshots, I'll be using my "pg-migration" project but you can use any GitHub project you desire. I strongly encourage you to follow along.

Preparation

Lets Go

Open the "project" for GitHub. You want to fork the target repository. What this does is create a copy of the project to your GitHub account. This becomes your "remote working" space.

Fork button on GitHub

Upon clicking this, you see something like the following.

Processing screen on GitHub

After the process, you'll be taken to the forked instance which will appear quite identical to the original. For example, the readme will be showing.

At this point, you clone the repository with git. Cloning is similar to check out used in TFS or Subversion; there is more to it but for now consider them the same thing. You want to clone your fork and not the original in order to be prepared to publish changes for a pull request later.

Getting the clone address

With GitKraken, there are several ways to close a repository but the most direct are to select File -> Clone. You'll be presented with a dialog like the following. You may use the URL option or the GitHub.com option. For simplicity, I'll show a screenshot of the URL section.

Cloning in GitKraken

Once you've cloned you'll be on the default branch master, before doing anything you should create a branch specific to your current efforts. The common branch naming convention is:

  • feature: feature/feature-name-or-id
  • issue/bug: issue/issue-id
  • explore or hacking1: hacking

Branching in GitKraken

Click on "branch" and enter a name for it and hit enter. If you're just doing the steps to follow along, use hacking as the branch name otherwise select accordingly. Upon creating the branch, your working copy will be set to the branch. The working copy is the source code that you can edit.

If you open the folder in Finder or Windows Explorer, you should see the source files as, well, files.

In GitKraken, the active branch has a green checkmark next to it.

Active Branch

You are now ready to work. You can put comments or make changes. If you want to keep the changes, commit them. When you commit in git you are only committing to your clone -- that is, the git repository on your computer. Git works by keeping a full copy of the version control repository locally. There is a complete copy on the server as well but the two are only indirectly linked -- you have to give it the push command to send the changes to the server.

Consider the git repository on your computer to be temporary. Any changes you want to truly keep should be "pushed" to Github. This makes hacking in a throwaway branch on your local repository super easy but it also means that you can lose work you want to keep. Be mindful of this and push when appropriate.

Make a few changes or add notes for yourself -- anything really -- and save the modification. Let's commit these changes. In GitKraken, the command becomes present when it detects changes to your working copy. Select the line that says // WIP and you'll see something like the following. Note that the UI changes layout depending on the size of the window.

GitKraken Commit UI

Move your modified files to staged -- this indicates your intent to include these files in your commit -- fill in the summary and click "Commit".

The UI updates to reflect that hacking has moved forward one node from master and you'll see your notes. From here, I encourage you to explore the UI of GitKraken or SourceTree.

Once you are ready, I encourage you to push your changes to the repository on GitHub. Remember that you forked the project and so:

  1. You have write access to the repository.
  2. Changes to your forked repository are not going to affect the source project.

Click the push button in the toolbar and you'll be presented with the following dialog. Simply click Submit.

GitKraken Push dialog

This dialog is indicating you're going to send this to the remote called origin (automatically assigned to the clone source) / branch hacking.

On the GitHub side of things, you'll see the following:

GitHub after the push

Should you want the author of the source project to include your changes in the main project (and assuming you've followed the project's contributing documentation), you can issue a pull request.

For now, that is the basic usage of git to collaborate on an existing project. There are other things you need to be aware of such as merging and overall branch management but I'll be covering those in future articles. For now, this should get you started.

Enjoy hacking.


  1. I've invented this. It's a convention I use to avoid contaminating master.

Tools of Open Source

 •  Filed under OSS, GitHub, travis-ci, git, software engineering

There are common tools and concepts used in open source. Because this site is aimed at getting folks in to open source, it's occurred to me that a post to at least introduce you to related tools and give you a primer.

Of course, if you search individual for these tools, there'll be a lot better tool-specific write ups then I could ever do. But, this should act as a basic primer and launching pad to get started with these tools. At the end of each description, you'll find a source for more information.

Note: This article is still undergoing minor revision and additions but I felt it was complete and useful enough to publish now

git (version control)

git is a principle tool very commonly used in open source. There are other tools used, depending on the site used and the preference of the author but it's fair to say that git is far and away the most popular right now.

There are several ways to install git but following are probably the most common.

I'll cover basic usage in a fourth coming article but meanwhile, know that it exists and you'll likely need it to work with open source. (Although, do know that you can download and view open source without using git at all)

github

Github is a separate and distinct service from git although, the two almost always go hand in hand. There are alternative to github such as bitbucket.org and gitlab but I expect that most open source we explore on this site will be on github.

So, what is github? The service bills itself as social coding platform and I'd say they achieve that objective.

At its core, github is a place to publish your source code and then collaborate with others on it. They provide a few tools to facilitate this such as in-browser source code viewing, the wiki, the issues list and the concept of "pull requests". At it's core, all tools are designed to provide friendly, productive collaboration.

unit-testing

Unit testing is not a product but a software engineering concept. In open source, different users are making various changes to a given code base. One developer doesn't necessarily know the purpose, expected or possible input or the output of a given component (unit) of software and therefore could accidentally change it in a manor that introduces bugs elsewhere. These bugs may ever surface in manual testing because you'd need to know to look for them.

Unit tests help prevent this; they allow you to implement an automatic test to verify that a component works and more importantly, keeps working as intended.

Any time you are changing open source source code, you're going to be running these tests dozens and dozens of time. When I cover OSS for an article, I'll discuss running the associated tests.

Continuous Integration (CI)

Continuous Integration, like unit testing, is not a product but a software engineering concept. The high level purpose is to automate the process of taking the source code, compiling/building it3, running the unit tests as well as others and providing a report to the author and team.

This occurs when a contributor (you) makes a change to the codebase and request the the author includes the contributed change in the main code base (pull request)

Similar to git, there is a dominate product in the github world called travis-ci. This product is "10000% free" for open source project with awesome integration with github. Therefore, it's quite ubiquitous.

  1. My favorite but I wish it worked on Linux.

  2. Git for the CLI does exist but there are different flavors. The detail are beyond this article but if you choose the CLI for Windows, bear this in mind.

  3. Even non-compiled languages such a JavaScript and Python commonly go through a build process which might include compressing the code and/or linting it