Git, GitHub and an open source .NET project – Part 5

I have used the open source enterprise search platform Solr for a number of years now and on a recent project have been using the open source SolrNet .NET client library. The SolrNet library lacked a feature I required when used with the bundled Service Locator implementation. A number of people had been asking for the same feature so I decided to jump in and implement it.

This is the final part of my journey into learning Git, using GitHub and contributing to an open source project.

GitHub Workflow

As I discussed in an earlier post, the typical workflow of contributors to an open source project hosted on GitHub can be a bit intimidating. It involves the following steps:

  • Fork
  • Clone
  • Write and commit code
  • Push
  • Submit pull request

I have gone through forking a project and cloning the repository. Writing and committing code to your local repository. Pushing those changes up to your cloned repository on GitHub. Now all that is left is to submit a pull request to the master project.

Pull Request

A pull request wraps up a number of commits so that another interested party can review them and decide whether or not to include them in a master project. GitHub makes this incredibly easy.

GitHub - pull request

I navigated to my paulbouwer/SolrNet repository on GitHub and after confirming the commit details via the Commits tab clicked on the Pull Request button.

GitHub - pull request

I wrote a comment around the commits I was submitting in the pull request. GitHub always makes it clear as to what is going on. Note the You’re asking mausch to pull 1 commit into mausch/master from paulbouwer/master.

GitHub - pull request

GitHub allows you to verify the commits included in the pull request via the Commits tab.

GitHub - pull request

GitHub allows you to verify the files and diffs on those files included in the pull request via the Files Changed tab. I had a number of issues with line ending differences on my files vs the master project – so a great tip is to pay attention to these. Mauricio kindly resolved these for me.

GitHub - pull request

GitHub allows you to preview your pull request message via the Preview submenu on the Preview Discussion tab. I finally submitted the pull request by clicking on the Send pull request button.

GitHub - pull request

The pull request has now been added to the pull requests queue of the master project mausch/SolrNet. GitHub again makes it clear as to what is going on. Note the paulbouwer wants someone to pull 1 commit into mausch/master from paulbouwer/master.

GitHub - pull request

Clicking on the Pull Requests tab in the master project mausch/SolrNet shows the current pull request queue and confirms that my pull request is in it.

Acceptance

Commits accepted into master project

I was notified by GitHub via email that my commit had been accepted by into the master project mausch/SolrNet. I confirmed this by clicking on the Commits tab on the master project page.

Issue 83 closed

I also confirmed that the feature I had worked on was now closed in the SolrNet issues list. It felt good – my commit had been accepted into the master SolrNet project.

End of a journey

This has been an incredible journey and I can highly recommend dedicating some time and code to an open source project. The satisfaction of contributing to a project used by a community is something else. You also get a lot back – my knowledge of Git has improved and the insight into how other people code and their thought and design processes has been invaluable.

There’s nothing stopping you – find a project that you believe in and help out !

Git, GitHub and an open source .NET project – Part 4

I have used the open source enterprise search platform Solr for a number of years now and on a recent project have been using the open source SolrNet .NET client library. The SolrNet library lacked a feature I required when used with the bundled Service Locator implementation. A number of people had been asking for the same feature so I decided to jump in and implement it.

This is part 4 of my journey into learning Git, using GitHub and contributing to an open source project.

The feature

The feature in SolrNet that I was interested in updating revolved around using the built in Service Locator to support multi-tenancy.

SolrNet Issue 83

No one had volunteered their time to implement this feature as can be seen by a thread in the SolrNet Google Group, so I decided to jump in and implement the feature.

SolrNet Google Group

Committing the implemented feature

After implementing the feature I was ready to commit my code to my local repository which was located in my C:\Projects\GitHub\SolrNet folder. I ran the git status command via the Git Bash shell. This will show any new files that I have created or any changes to existing files that I have made.

git status

git status

The Changed but not updated list refers to files that have been modified in the working directory but have not yet been staged. The Untracked files list refers to new files in the working directory that Git does not have in a previous snapshot (commit). All these files need to be added to the staging area in preparation for the commit.

The staging area is where changes can be grouped before being committed. This gives you a lot of flexibility in what actually goes into a commit. There is a nice explanation on the git ready site.

I ran the git add command via the Git Bash shell for each of the files that I needed to add to the staging area.

git add

git add

I then ran the git status command via the Git Bash shell again to confirm that the files were now all in the staging area of my local repository.

git status

I ran the git commit command via the Git Bash shell to commit the changes from the staging area. The -m switch allows you to specify the commit message. I used the issue details Issue 83: Support for multi core using ServiceLocator as my commit message.

git commit -m

git commit

I ran the git status command again via the Git Bash shell again to confirm that all staged changes had been committed in my local repository.

git status

Pushing commits to public repository

You may have noticed the following message in the last screenshot: Your branch is ahead of ‘origin/master’ by 1 commit. This is showing that my local repository now has a commit that is not in my public paulbouwer/SolrNet repository. To confirm that the name origin references my public paulbouwer/SolrNet repository I ran the git remote command via the Git Bash shell. The -v switch switches on verbose messages and the show -n action and switch specifies the name of the remote.

git remote -v show -n

git remote

I next ran the git push command via the Git Bash shell to push my commit to my public paulbouwer/SolrNet repository on GitHub. I am pushing my local changes to the master branch on my origin remote. Note that the password here is not your passphrase but your GitHub account password.

git push

git push

A final git status command via the Git Bash shell confirms that my local branch is no longer out of sync with my public paulbouwer/SolrNet repository on GitHub.

git status

Confirmation

The commit pushed up to my public paulbouwer/SolrNet repository on GitHub is clearly visible under the Commits tab. Clicking on the commit hyperlink for the commit will take you to the details of the commit.

GitHub Commits

Next is submitting a pull request and getting the code accepted into the master repository …

Git, GitHub and an open source .NET project – Part 3

I have used the open source enterprise search platform Solr for a number of years now and on a recent project have been using the open source SolrNet .NET client library. The SolrNet library lacked a feature I required when used with the bundled Service Locator implementation. A number of people had been asking for the same feature so I decided to jump in and implement it.

This is part 3 of my journey into learning Git, using GitHub and contributing to an open source project.

Configure Git Options

Since I was about to fork a project and start dealing with code it seems like a good time to configure my identity within Git. Git uses your name and email address to sign your commits.

This can be achieved via the Git Bash shell by typing the following commands:

git config --global user.name "your_full_name" git config --global user.email "your_email_address"

The global switch applies this information to all of your projects. If you would like to override options for a particular project leave out the –global switch when in that project.

The following command will list out all your configured options:

git config --list

git config

GitHub Workflow

The typical workflow of contributors to an open source project hosted on GitHub can be a bit intimidating. It involves the following steps:

  • Fork
  • Clone
  • Write and commit code
  • Push
  • Submit pull request

I’ll discuss the first two steps (fork, clone) in this post and will cover the remainder in the next two posts.

Forking the SolrNet Project

The SolrNet project was created by Mauricio Scheffer and is hosted on GitHub at https://github.com/mausch/SolrNet.

To contribute code to a project on GitHub typically starts with you having to fork the project. Forking the project creates a copy of the master repository with a complete history under your GitHub account. This is great since it allows you to start contributing code and have the changes publically available to anyone who wants them – you don’t need commit access to the master project.

Fork project on GitHub

I navigated to the master project mausch/SolrNet page and clicked on the Fork button.

Forked project on GitHub

GitHub managed the forking of the master project and created a forked copy for me. It is now available at https://github.com/paulbouwer/SolrNet. GitHub also clearly shows that the project has been forked from the original project mausch/SolrNet.

Git is a distributed version control system which allows greater flexibility in how developers contribute and collaborate on projects. I don’t have commit access to the master repository mausch/SolrNet so GitHub helped me fork the repository to create a public repository paulbouwer/SolrNet to which I have read/commit access. So now I can commit changes into my paulbouwer/SolrNet repository and Mauricio can pull any of my commits into the master mausch/SolrNet repository (if he wants them).

Cloning your GitHub repository

A typical and common workflow in Git is to have a private local copy of your public repository. This allows you to have a working space that is under revision control. Once you are happy with the changes you have implemented you can roll them up into a single commit to your public repository and ask the maintainer of the master project to pull your commit into the master repository.

Obtaining a private local copy of your public repository is achieved using the git clone command. As the name suggests this is a clone of the repository (as opposed to a checkout in SVN). The cloned repository contains its own copy of the entire history of the project.

First we need the public repository URL from GitHub. I was having some firewall issues with SSH so decided to use my HTTP URL.

GitHub repository HTTPS URL

I ran the git clone command from the C:\Projects\GitHub folder via Git Bash shell. When prompted for a password enter the key passphrase for the SSH key registered with GitHub.

git clone https://paulbouwer@github.com/paulbouwer/SolrNet.git

Clone project

Confirm files

This successfully cloned my public paulbouwer/SolrNet repository into my C:\Projects\GitHub\SolrNet folder as can be seen above. You can also see that the master branch is the active branch at the moment.

You can also clone a repository via TortoiseGit by clicking on Git Clone … on the right click context menu in Windows Explorer in the C:\Projects\GitHub folder.

 TortoiseGit - Git Clone ...

After providing your SSH key passphrase TortoiseGit will begin the clone.

TortoiseGit - cloning

TortoiseGit - confirm files

TortoiseGit has successfully cloned my public paulbouwer/SolrNet repository into my C:\Projects\GitHub\SolrNet folder as can be seen above. This is missing some of the contextual information we saw in the Git Bash shell such as the current active branch. I prefer using the Git Bash shell as it gives me more information and finer grained control. I will continue purely with the Git Bash shell for the rest of this series of posts.

Adding remotes

Now that I have a local copy of my repository I need a mechanism to manage changes between it and my public repository paulbouwer/SolrNet. I also need to manage changes between my local repository and the master repository mausch/SolrNet. This is achieved using the remotes concept in Git.

From the Working with Remotes section of the Pro Git book:

Remote repositories are versions of your project that are hosted on the Internet or network somewhere. You can have several of them, each of which generally is either read-only or read/write for you. Collaborating with others involves managing these remote repositories and pushing and pulling data to and from them when you need to share work

Master repository on GitHub

I obtained the HTTP URL of the master repository mausch/SolrNet.

I added a link to the master repository using the git remote command via the Git Bash shell. I used the typical remote name of upstream to denote the master repository mausch/SolrNet. I used the git remote command to also verify that the remote was added correctly.

git remote add upstream https://github.com/mausch/SolrNet.git git remote –v

Add and verify remotes

The remote link to the master repository has been successfully added under the name upstream. But what is that remote named origin and how did it get added? When you clone a repository, Git automatically adds a remote to the repository you have cloned with the name of origin.

I then ran the git fetch command via the Git Bash shell. This fetches any changes from my upstream remote and pulls them down into my local repository. I did not do this for my origin remote since I know that I have just cloned my local repository from it.

git fetch upstream

Fetching upstream changes

The git fetch command fetches changes across all the available branches.

The final step is now to run the git merge command via the Git Bash shell. This will merge the fetched upstream changes into my local repository.

git merge upstream/master

Merge upstream changes

I was only concerned about the master branch changes and therefore that is all that I merged in from the upstream fetch. You can also see that since I had just forked my public repository and cloned my local repository from that there were no changes to merge in.

Now I have a public repository that I can use for pull requests and an up to date local repository that is ready for me to start coding in. Next is writing some code …

Git, GitHub and an open source .NET project – Part 2

I have used the open source enterprise search platform Solr for a number of years now and on a recent project have been using the open source SolrNet .NET client library. The SolrNet library lacked a feature I required when used with the bundled Service Locator implementation. A number of people had been asking for the same feature so I decided to jump in and implement it.

This is part 2 of my journey into learning Git, using GitHub and contributing to an open source project.

What is GitHub ?

GitHub_LogoGitHub is the popular web-based hosting service for projects that use the Git revision control system. It has a large number of project management, code hosting and community based features.

Sign up for GitHub

GitHub offers a free account for open source projects. This account has an unlimited number of public repositories and public collaborators. There are also plans that cater for private repositories and collaborators.

Git_Part2_GitHubSignup

The source code for the SolrNet project is hosted on GitHub so I signed up for the free plan and created myself an account on GitHub.

Git_Part2_GitHubKeys

Once you have updated the Public Profile and Email Addresses sections of your account you will notice that you need to associate an SSH public key with your GitHub account.

Generate an SSH key

Fire up the PuTTY Key Generator executable puttygen.exe found in the PuTTY install folder.

Git_Part2_KeyGen1

Select the SSH-2 RSA radio button and ensure that the number of bits is set to 1024. Click the Generate button to generate the public/private key pair.

Git_Part2_KeyGen2

Cryptography calls for unpredictable random numbers. A simple way to obtain this randomness is to generate it from the user. The PuTTY Key Generator uses random mouse movements to generate randomness.

Git_Part2_KeyGen3

Give the generated key a comment and provide a passphrase. The passphrase provides an extra layer of security for your key. This is not my actual key but even if it was – all that is visible here is my public key which is meant for public distribution anyway …

Git_Part2_KeyGen4

Create a .ssh folder in your home folder. I created a C:\Users\paul\.ssh folder. Save your public key into this folder by clicking on the Save public key button.

Git_Part2_KeyGen5

Save the private key into your .ssh folder by clicking on the Save private key button.

Git_Part2_KeyGen6

You should now have a public/private SSH key pair for GitHub. My public key is github_rsa and my private key is github_rsa.ppk. Never let anyone have access to your private key !

Add public key to GitHub

Now we are ready to add our newly generated public SSH key to GitHub. Highlight the text in the Public key text box and copy it to the clipboard (CTRL-C).

 Git_Part2_AddKey1

If you have already closed the PuTTY Key Generator I’ll show you how to load the key back up. Fire up the PuTTY Key Generator executable again and click on the Load button.

Git_Part2_AddKey2

Select your GitHub private key file and click on the Open button.

Git_Part2_AddKey3

You’ll be required to provide your passphrase to load the private key.

 Git_Part2_AddKey1

Now highlight the text in the public key text box and copy it to the clipboard (CTRL-C).

Git_Part2_GitHubKeys

Go back to the SSH Public Key section in your GitHub account. Click on the Add another public key link.

Git_Part2_AddKey4

Paste (CTRL-V) the public key from your clipboard into the Key text box. Provide a Title for your key and click on the Add key button.

Git_Part2_AddKey5

GitHub is now set up with your SSH public key.

Next is forking the SolrNet project …

Git, GitHub and an open source .NET project – Part 1

I have used the open source enterprise search platform Solr for a number of years now and on a recent project have been using the open source SolrNet .NET client library. The SolrNet library lacked a feature I required when used with the bundled Service Locator implementation. A number of people had been asking for the same feature so I decided to jump in and implement it.

This is part 1 of my journey into learning Git, using GitHub and contributing to an open source project.

What is Git ?

imageGit is a free and open source, distributed version control system initially designed and developed by Linus Torvalds of Linux fame. Even though there are fundamental differences from a revision control system such as Subversion, there are numerous books and documentation available to help you.

The major difference with Subversion is that every Git working directory is a full-fledged repository with complete history and full revision tracking capabilities, not dependent on network access or a central server. This takes some time to get used to but once the light comes on it is pretty cool.

Install PuTTY

If you want to use GitHub you’ll need an SSH key. Even though Git comes with an SSH client, I highly recommended that you install PuTTY on Windows. This is a free Telnet/SSH client that has a number of utilities that make dealing with SSH keys and passphrases more pleasant.

I downloaded and installed the PuTTY 0.60 Windows Installer.image4

Make sure that you associate .PPK (PuTTY Private Key) files with Pageant (SSH authentication agent) and PuTTYgen (SSH key generation utility).

Install Git

To install Git on Windows you need to download Git for Windows and install it. I downloaded and installed the full installer for official Git 1.7.3.1.

image11

I was only interested in using the Git Bash shell via the Windows Explorer context menu and so selected the Git Bash Here option. Since I was installing TortoiseGit for GUI based Git interactions I did not want my context menu cluttered with the Git GUI Here option.

image13

I selected the Use Git Bash only option here since I wanted my Git environment to work smoothly and remain contained. I was also only ever going to use command line Git from the Git Bash shell.

image14

Since I have PuTTY and TortoiseSVN already installed the Git installer has picked up the various Plink.exe executables. Plink is a command line interface to the PuTTY libraries that tools such as Git or TortoiseSVN/TortoiseGit use to provide SSH capabilities.

I selected the Use (Tortoise)Plink option and made sure that the file path pointed to the Plink executable in my PuTTY install folder. Now Git will use PuTTY to manage its SSH requirements.

image15

Git can translate line endings between Windows and Unix style line endings. I selected the Checkout as-is, commit as-is option as this would not perform any conversions. I figured that if I was working on a Windows project it should have Windows line endings.

image

Confirm that Git for Windows has been successfully installed by firing up the Git Bash shell. I fired mine up in my projects folder.

Install TortoiseGit

TortoiseGit provides an extension to Windows Explorer that works with a Git repository. Some people feel more comfortable using graphical tools. I prefer to have both since I can use whichever one helps me get a specific task done faster or easier.

I downloaded and installed the Tortoise Git 1.5.8.0 Windows installer.

image20

Like Git, TortoiseGit also can be made to use the PuTTY Plink executable.

image21

I selected all the features and completed the installation. That was easy !

Git enabled !

I now had Git installed and was equipped with both the command line Git Bash shell and GUI based TortoiseGit options.

Next is setting up GitHub …

Git, GitHub and an open source .NET project – Introduction

I have used the open source enterprise search platform Solr for a number of years now and on a recent project have been using the open source SolrNet .NET client library. The SolrNet library lacked a feature I required when used with the bundled Service Locator implementation. A number of people had been asking for the same feature so I decided to jump in and implement it.

This is my journey into learning Git, using GitHub and contributing to an open source project. I highly recommend the experience – you learn a great deal from reading and contributing to code that is so highly visible.

I have split my journey into the following 5 parts: