Humanitarian Toolbox Codeathon .NET South East - Coding for the Greater Good

On Saturday (20th January) we held a special .NET South East event, spending the day ‘coding for the greater good’ on the Humanitarian Toolbox allReady project. We were very excited to be joined by Richard Campbell, one of the co-founders of Humanitarian Toolbox and co-host of the popular .NET Rocks Podcast. A team of 19 volunteers joined us to contribute towards the project during the day, all first time contributors to the project. For many, this was also their first time working on an open source project and GitHub.

Richard Campbell - Humanitarian Toolbox co-founder
Richard Campbell Introducing the Humanitarian Toolbox to our Team.

Planning

The possibility of running a codeathon came together quite recently and once I was able to arrange with Richard for him to join us, I kicked the planning into high gear. The first problem when trying to host an event like this is usually finding a suitable venue. In my case this was not a problem as Madgex, my employer, are very supportive of these events and were immediately open to the idea of hosting it. We have three neighbouring meeting rooms which can be opened up into one larger space. We do this for our monthly .NET South East meetups too and it creates a very reasonable working area.

We picked the date around Richard’s travel plans for NDC London. Richard and Carl were recording their shows at the event and Richard had a day spare following the conference which was ideal for hosting the codeathon. I created a meetup event to allow people to begin reserving their place at the codeathon. Initially I set a limit of 14 spaces until I’d had chance to fully assess the logistics of running the event. In the end we raised this to 18 spaces.

So we now had a date and a venue planned; the final  thing I started to put into place was food. I wanted to ensure that our contributors didn’t run out of steam too early in the day and as we all know, the best fuel for developers is pizza!! Madgex kindly agreed to pay for the pizzas and also for some post event catering to re-fuel before our regular meetup began.

Organising GitHub Issues

After the Christmas holidays I started to organise the issues in the project. allReady has evolved over the last few years into a quite large application. As a result, the complexity level for those starting out with the project has increased. When running a codeathon I am conscious that for some people, everything may be new and so I wanted to try to make the barrier of entry as low as possible. Part of this includes having a good range of smaller issues that can be easily tackled by first-timers.

Fortunately, one of the things we had recently been focusing on is the need to improve the user experience (UX) of the application. The application is very much functional, but not always intuitive for a new user. As a result of this I spoke to a friend of mine, Chris, a UX designer working in Brighton. We spent a couple of hours reviewing the application and during that session he found a number of small, but neccesary changes we could make to give us some quick win improvements to the UX.

After that meeting I came away with a lot of subtle changes that I was able to create issues for; perfect for the codeathon. These may not see very exciting on the surface but they will really help improve the usability of the application. They were also small enough that they can easily be tackled in one day as someone new to the project finds their feet. I hoped these could be good gateway issues before people started to tackle more complex feature requirements.

In the week leading up to the event I spent time organising the final logistics, such as ensuring we would have sufficient power connections for all of the laptops. I was also able to increase the RSVP limit as we wanted to make the most of the opportunity and allow as many members of our community to contribute. I also reached out to some local charities to see if they would be interested in attending the event to see how the application may be able to help with their own requirements.

I am very thankful to some of my colleagues at Madgex who were also helping to make sure we had everything in place ready for the weekend. This was particularly useful as I was at the NDC London conference the three days prior to the event so couldn’t be there in person to perform any last minute preparations.

Codeathon

On the day of the codeathon I set off by train to Brighton. Once there, my first stop was to pick up Richard from his hotel. Dan, the organiser of .NET Oxford was also staying at the same hotel and would be joining us for the event. It was great to finally meet Dan in person after many months of chatting via Twitter about running our user groups.

Together, the three of us set off for the Madgex office. One of my colleagues, Chris was already there and had been helping out by letting the early arrivals into the building.

The next 45 minutes to an hour were spent organising the meeting room space. Again, my colleagues had been very helpful, having set up a few things the day before. We just needed to ensure we had the suitable power points for the numerous devices we’d be running on the day. Ricky, our IT support technician at Madgex had kindly come in on his weekend to help with the setup and to be on hand for any technical challenges.

The setup went very smoothly and soon we had most of volunteers for the day settled in. Nearly everyone had been able to get the project cloned onto their laptops and tested prior to the event. This is extremely useful and meant that we were ready to start the event and begin coding with very little delay. At codeathons this really does help with the productivity as we can focus on code, rather than machine preparation.

At about 9:20am we were all ready to begin. We started with a short introduction from Richard who shared the history behind Humanitarian Toolbox and the goals of the allReady project we would be working on. Our volunteers listened with rapt attention and it was fantastic to have Richard with us to share his passion for the charity he has founded.

Humanitarian Toolbox Codeathon introduction

After Richard finished his introduction, I spent a few minutes speaking about the technical stack and the basic flow for working on issues and submitting pull requests. I find it useful to review this flow before starting, especially when we have some first time open source contributors in the room. In hindsight I probably needed to mention a few other things to make it easier for people to get going which I’ll include in my slide deck for future events.

With the introductions complete, we commenced coding. Everyone was heads down very quickly, choosing issues to work on and producing code to address them. As expected, there were quite a few questions along the way and I hope I was able to help everyone get started without too much of a delay. There’s a lot to take on and learn at an event like this and I thank everyone for being very patient as I worked through the various questions.

In under 1 hour we had had our first pull request to the project and after that the flood gates opened and more streamed in. I did my best to keep up with the requests, performing code reviews before merging them into the project. Our AppVeyor account was struggling under the load a little. Each pull request to the project triggers a build on the AppVeyor system. This is very useful to be able to verify that the code included in the PR builds and that the tests all pass. As we had many PR’s coming in concurrently, it did start to creak at the seams a little. Worth noting for future events to see if we can increase the capacity of the account.

We had a brief lunchtime break for pizza at around 12:45pm, which was a good chance for people to break from their screens and chat about the progress so far. The morning had flown past at a great rate and already the team had achieved a great deal. The team were eager to get going again and before long were back at their laptops, working on the next set of pull requests!

Codeathon contributors in action

During the afternoon we had organised a series of User Experience (UX) user testing sessions. We are conscious that the project has been developed mostly by backend developers and as a result, while functional, the User Interface (UI) and UX of the project leave something to be desired. This is now a focus on the project to see what we can change and improve to make it as easy to use as possible. A big thanks to my friend Chris for joining us to run the user testing sessions and to our willing test subjects, Jenny, Zen and my wife Rhiannon. It proved really useful and we now have a number of good suggestions from Chris for changes that we can make to resolve some difficulties identified during the testing.

The afternoon seemed to go even faster than the morning, with more PRs being made as people became more familiar with the project and the workflow. By 5pm we had made significant progress and it was time to wrap up the event. We concluded with some sandwiches provided from a local caterer which were very welcome after our busy afternoon.

Achievements

Including myself and Richard we had 17 people working on the project all day, and a further 4 contributors for the additional work being done in the afternoon to perform the UX testing. This was a really great turnout and it meant we could get through a lot of work in a relatively short space of time. I can’t thank everyone enough for coming along and helping to make the day such a success. On reflection, the number we had was just about right. Any more would have been harder for me to support without delaying people.

In total we had 30 pull requests opened during the event. That’s thirty issues within the project being addressed and fixed which is pretty incredible. That may be close to a record for a single day Humanitarian Toolbox event! I was able to review and merge 18 of those during the day as well, which means that code is already active in the project. I will endeavour to get through the reviews of the remaining 12 PRs as soon as possible.

How can you help?

If you like the sound of this project and this style of event, we’d love for people to join us in contributing to allReady. For those that took part in the codeathon, we hope many will continue contributing to the project too. During the next couple of months there is a global Microsoft MVP (Most Valuable Professional) event running which is a virtual codeathon to get Microsoft MVPs from around the world contributing to the project. I am helping to organise and run that event and hope to see lots of activity on the project leading up to the Global MVP summit event in March.

This is a great time for newcomers to join the project as we have lots of experts on hand to support you and help you get started. The best place to start is to visit the GitHub project repository. From there you can view the open issues and jump in wherever you feel comfortable. If you need support, just let us know and we can help out.

I have started a series of videos explaining how you can get started with open source contributions and showing the technical steps. You can view these on my YouTube channel.

Summary

I’d like to wrap up with another huge thank you to everyone who helped in some way with organising this event and especially to those contributors who took part during the day. It was a great showing from the community and I hope everyone enjoyed the day as much as I did. The aim of the event was to introduce people to the project and get them past the learning curve for contributing to an open source project. A big thanks to Madgex for supporting the event with the use of their meeting rooms, as well as for providing some food to keep the troops fuelled up. In my opinion it was a huge success and I hope that we can arrange future events to continue the good work from everyone who contributed.

Forking and Cloning from GitHub Contributing to open source projects (Part 1)

In this post I’m going to share the initial steps that you will need to take in order to be begin contributing to an open source project. I’ve covered this more generally in the past and wanted to provide a more focused post that covered these steps for a new open source contributor. For this post we’ll use the Humanitarian Toolbox allReady project as our example.

Forking a Repository

When beginning to contribute to a project on GitHub, your first step is to fork the repository. This creates a copy of that repository under your own account enabling you to begin working with the code. The rights to public repositories will be such that you can view the code, but not directly commit into the repository or create branches. This allows the project owners to control changes within their codebase. Changes are made via pull requests; which we’ll cover in a future post.

The forking step creates a copy to which you do have permission to commit and branch on and you can consider this your working copy of the project. You can make changes and commits here, safe in the knowledge that you will not affect the main repository.

The process of forking on GitHub is very simple. Make sure you are logged into your account on GitHub and then open the project you are interested in contributing to. In this example I’ll navigate to https://github.com/htbox/allready. Once inside the repository you will see a “Fork” button in the upon right hand corner of the UI. Click on this button to begin the automatic forking process.

 

GitHub Fork Button

 

 

GitHub forking progress

Within a few seconds you’ll have your completed fork.

Cloning your Fork

Now that you have your fork, the next step is to clone the code down to your local development machine. Again, GitHub make this quite simple in their UI. To clone a repository you will need its URL. Clicking on the “Clone or download” button will open a UI showing the Git URL. A button to the right hand side of the URL allows you to copy it into your clipboard.

GitHub Clone or Download button

To perform the clone operation I’m going to demonstrate using the command line. There are various graphical tools you can use to work with Git repositories but for simple procedures, the command line is often fastest.

Open a command window and navigate to the path where you would like to clone the repository.

Use the following command to begin a clone:

git clone https://github.com/stevejgordon-demo/allReady.git

Here we’ve pasted in the URL of the fork that we just copied as the argument to the “git clone” command. You will see the output of the clone command as it clones the contents of your repository onto your local device.

Git clone progress

Once the command completes you will have a new folder containing the cloned repository. We can validate this by running the “dir” command.

Directory after cloning

Next we’ll need to navigate into the newly cloned folder. Will do that with the following command:

cd allReady

Registering an Upstream Remote

The final step is to setup a remote which points to the main repository. Remotes simply represent paths or URLs to other versions of your repository. In our case, as we cloned from our fork on GitHub a default remote will have been setup for us called origin. This origin allows us to push and pull code from our forked repository hosted on GitHub. We can list the currently configured remotes on our machine using the “git remote” command.

Default git remote for origin

Pushing and pulling from your own fork is very useful and this will be how you will work with the project most often. However, when working on that code, you’ll want to be starting from the most recent version of the code from the main allReady repository. That code may have been updated and changed since you first made your fork. In order to get access to that latest code, we’ll setup a second remote which points to the main allReady repository. We will not have commit rights there, so we cannot push changes, however, we will be able to fetch the latest commits that have occurred.

To create a new remote we use the “git remote add” command, passing in a name for the new remote and the URL as arguments. First we need the git clone URL for the remote we want to add. We can get this by heading back to GitHub in our browser. From our fork we can use the convenience link to take us back to the main repository from which we forked it.

Switch to fork parent repository on GitHub

Once back in the allReady main project we can use the same steps as we previously used to access the clone URL via the “Clone or download” button and copy it to our clipboard.

Back in our command window; to add our remote for our allReady example we’ll use:

git remote add upstream https://github.com/HTBox/allReady.git

We could name the remote anything we like, but the convention is to use upstream, so we’ll follow that.

If we run the “git remote” command again we can verify that we now have two remotes.

After adding upstream remote

Summary

That’s as far as we’ll take it in this post. We have forked a copy of a repository, in this case allReady, and then cloned the code down to our local machine. We’ve down the work needed to setup an extra remote and we are now in a position to begin working on our first issue. We’ll cover that in a future post.

If you are a visual learner, then I have a video which covers the topics in this post available up on my YouTube Channel

Other posts in this series

Part 1 – This post
Part 2 – Working on Your First GitHub Issue