Open Source Continued: Humanitarian Toolbox and AllReady

This post is one in a series of posts I’ll be writing on contributing to the AllReady project.

In my previous blog post, I talked about my foray into open source development. Coming from a purely TFS background with no knowledge of Git or GitHub, I was apprehensive at first, but after submitting my first PR and getting some valuable feedback from the project owner, I helped migrate a fairly simple repository to C#6 syntax and learned about GitHub and Git.

My next step was to find a repository which would challenge me a bit more, and force me into more advanced scenarios with Git (well, advanced for a TFS guy!) like merging and rebasing.

I found that repository; the AllReady repository, which is run by Humanitarian Toolbox.


What is AllReady?

Being a daily user of NServiceBus, I regularly follow the blogs of most of their developers. I happened upon a blog post by Sean Feldman about an open source project by Humanitarian Toolbox called AllReady. After reading the post, I went to check it out.

Humanitarian Toolbox (HTBox) is a charity supporting disaster relief organizations with open source software and services. The AllReady project is being built to provide disaster relief aid for organizations like the American Red Cross. The site is built using ASP.NET Core/MVC 6/EF7, uses async/await, and other cool frameworks like Jimmy Bogard’s MediatR. These are all things I wanted to learn.

Another bonus was I’ve always wanted to volunteer my time for a non-profit organization, but time restrictions always got in they way. For me, volunteering in the “traditional sense” (going to a disaster site to help hand out water, for example) was something I could never quite make happen. This was an opportunity to volunteer for an organization lending my skills as a developer on my schedule. If I couldn’t find time to be a volunteer in the field, then I could write software to help the volunteer in the field!

I looked at this as a great opportunity. I get to learn the latest and greatest Microsoft stack, volunteer my time coding on my schedule for a non-profit, as well as work with some great programmers. I decided to jump in with both feet.


My First Contribution

Contributing to a new repository is always a challenge, especially on a project like AllReady, which is more of a business-based application and not a framework. Not being privy to any use cases/requirements and not having any experience in the field of disaster relief, I was hesitant after opening up the MVC project.

Luckily, I found a “jump-in” label which was a high-level Issue to “Improve Unit Test Coverage” (which there was very little of). Building out unit tests for code is a great way to learn the code base and start to become familiar with the ubiquitous language of the domain.

ImproveUnitTestCoverage

I figured I would start with the simplest controller I could find, and work my way into more complex controllers as I gained confidence and support from the project owners.

Immediately, I was given feedback and guidance on my first contribution.

ListingTheControllers

ImmediateFeedbackFromProjectOwners


Submitting My First PR

After coding the unit tests for HomeController, I submitted my first PR.

I ran into problems when their build server (AppVeyor) failed my build, and for the first time heard a term called “rebase” in order to get my branch to build with the code changed to fix the build server.

RebaseRequest

But I had no idea what rebasing was, or how to do it.


You Don’t Know Git

I do not want to rehash what Git rebasing is as it’s been written about ad nauseam online and is one of the most asked questions about Git. The simplest way to comprehend it from a TFS point of view is:

  • you get the latest code from the master branch from the AllReady GitHub project (no, this will not overwrite your local changes)
  • you merge with your local master branch  (this does not overwrite your local changes)
  • you checkout the local branch on which you’ve been working (this still does not overwrite your local changes)
  • you “replay” your changes from your local branch on top of the latest version of the code you just pulled down

The last bullet point is a little strange to get used to because as a TFS developer, you are forced to work with a central repository and “merge” code in one of two ways:

  • check in what you have to TFS, and handle the merge conflicts as you go. Once you’ve successfully resolved the merge conflicts, your changes are now in the central repository. So you hope they’re correct
  • pull latest code and handle the merges “locally”. When you’re done, you still need to commit everything back into the central repository.

Either way, you’re always merging your code with “master”.

With Git’s rebasing, your taking all the changes you’ve been working on, and “committing” them into the latest code you just pulled down from the master branch. The best part is, any merge conflicts can be handled locally, instead of being tied to a central repository like TFS. This allows you to move at your own pace, not impact other developers that might be committing code and allows you time to run unit tests/smoke test, etc… all locally.

For those interested, Git’s rebase also allows you to re-write history to keep the branches and commits to those branches much easier to understand looking back in a file’s history. Something that is very helpful on a open source project with a lot of contributors.


Git Tips for the Visual Studio Developer

If you are a Visual Studio user (which I assume you are if you’re looking to commit to this repository), I highly recommend:

  • NOT working from your local master branch. Create a branch from the master branch, and work off of that. It makes it much easier to have a local “stable” master branch and makes it easier for the project owners/code reviewers to merge your PR.
  • closing your solution before beginning the rebasing process
  • using Visual Studio merge tool to resolve merge conflicts (unless you really love using Git command line for this)

When I tried my first rebase operation I still had the AllReady solution open in my IDE and I mistakenly though that the rebasing process was destroying my local commits! This is partially because I was working out of my local master branch, but also because as you rebase, your changes are replayed on top of the latest code you pulled down. My confusion was exasperated by the fact I was looking at all the controller code I had changed being constantly updated in the IDE as the rebase was in progress:

Luckily, I received some help from Bill Wagner, one of the project owners who finally walked me through the process and got me back on the right track

RebasingIsWipinOutMyChanges

If you are looking to contribute to AllReady (regardless of whether you are a Git newbie or a seasoned vet), I highly recommend these two blog posts written by Steve Gordon and David Paquette (both active contributors to AllReady) that walk you through all the Git rebasing steps in the context of the AllReady project:


How to Get Invovled

AllReady is searching for developers interested in contributing. If you are a seasoned vet with GitHub/Git, or a newbie that wants to get involved, we welcome your questions and contributions!

A good place to start is any Issues with a “jump-in” label on our Issues page. Please feel free to reach out to me @mgmccarthy or any of the other project owners or regular contributors. We’re happy to help you get started and answer any questions you might have.


In Closing/Lessons Learned

I’ve now been contributing to the AllReady project for months and the support of its project owners and regular contributors has been incredible. The spirit of collaboration and teaching are present in all the Issues, discussions and PR’s.

I have learned so much “already” about ASP.NET Core, met and collaborated with some world-class technologists and have a “warm and fuzzy feeling” for finally be able to volunteer my time for a non-profit organization helping to build next-gen software for disaster relief organizations like the American Red Cross.

A couple take-aways:

  • learn to work with small, local git branches, rebase often and try to keep your commits small and scoped to make it easier on the person reviewing your code to give you feedback.
  • remember, EVERYONE here is a volunteer (including the project owners). If your PR is not picked up for a couple days, or you do not hear back about an Issue for a couple days, be patient. People will get back to you
  • be prepared to handle constructive criticism in a professional and collaborative manner. Just because you think your way is the best way to solve a particular problem does not mean it is. At the heart of open source software if the spirit of collaboration and learning. If you embrace this mantra, you will have an amazing experience.
  • don’t be scared to say “I don’t know” or “I need help”. The support from the project group is amazing and people will take their time to explain things to you so you can understand a given problem on a deeper level. I had to admit publicly that I had no idea how to work with Git and how the rebasing process worked, but by being transparent about my lack of experience, I received a lot of help and guidance, and am now a better developer/contributor because of it.

In future blog posts, I’ll be discussing more specific technical challenges as it relates to working with AllReady.

Michael McCarthy

Read more posts by this author.