Maintaining an open-source project

This morning I read a short article on the maintainer of GitHub desktop, William Shepherd. For some reason, I kept seeing the article everywhere so eventually I surrendered to it. The post had a number of good points but the highlight for me was the advice to anyone maintaining an open-source project:

  • Have a clear vision of what you’d like your project to accomplish and be open to refining it when it makes sense
  • Have a detailed README that includes information on how to contribute to the project, submit bug reports, and a code of conduct
  • Work hard to make your project inclusive of all people from the start
  • Make your project easy to implement by eliminating the amount of work potential contributors have to do to build and run your project
  • Don’t put the needs of your project ahead of your own

You can read the full article on GitHub’s blog.

Commitment issues

You’ve been spending plenty of time together. You’ve had your ups and downs. As time’s gone on you’ve realised you like the way things are going and it’s time to commit.

Writing effective, communicative commit messages can make the world of difference to other members of your team. Just as with code comments or clear variable and function naming, good commit messages are worth putting some thought into.

First and foremost focus on communicating why the changes are being made. It’s easy to think commit messages are actually about what has changed, but reviewing the code will show you that. Why the code has change lets people know the intent of the change rather than the details of it. Good examples of commit titles are:

  • Update interface to the new branding
  • Add Dutch translation
  • Remove reference to Batmans true identity
  • Add GDPR compliance message

Once you’ve nailed your title follow up with a good description. For example:

Remove reference to Batmans true identity

The copyright text on Batmans website specifiys the copyright holder as “Wayne Enterprises”. This suggests that Batman has some association with the organisation. This update removes all connection between the two entities, protecting all parties. This fix addresses issue #391.

As you can see this message doesn’t contain any details about the code. It clearly highlights why the commit is being made and also connects the commit to a reported issue if one exists.

GitHub flow

I’ve recently been attempting to contribute to some open-source GitHub projects with varying degrees of success. One thing that’s extremely useful to do before you start contributing is to develop a basic understanding of the standard GitHub workflow.

It’s not especially complicated but it can be a real faff if you don’t do it correctly from the start.

Step 1 – Clone the repo

The first thing you’re going to need is your own copy of the project to work on. You do this by cloning the repo to your local machine where you’ll make your changes.

Step 2 – Create a branch

Now you’ve got a local copy you’ll want to create a separate branch for your specific contribution. For example, if you’re working on issue #3271 and issue #3244 you’ll want to create separate branches for each issue. It’s a good idea to name this something like fix/issue#3271 and fix/issue#3244 so you know which branch to submit for what issue once you’re done.

Step 3 – Make commits

Once you’ve made your changes within the appropriate branches make your commits. Commits tell the story of your changes, be sure to write clear concise comments that communicate your intent to other developers reading them.

Step 4 – Submit a pull request

Once you believe you’ve completed your changes create a pull request to submit them. Create one pull request for each issue and corresponding branch you’ve created. Pull request are a way of notifying the projects “owner” of your proposed changes for consideration.

Step 5 – Discuss and refine

It’s likely upon review there will be some conversation around the code and changes. Others may have ideas on different approaches and/or improvements to the update. You can continue to make changes and improvements to refine your solution as a result of these discussions. Just keep making those commits.

Step 6 – Deploy

This part you’re likely to be less involved with. If and when the “owner” decides to use your code they will likely deploy it into the master branch where it will then be tested along with all the other changes made in that round of updates. This is were things get exciting.

Step 7 – Release

Assuming everything is tickety-boo your code is then included in the next production release leaving you with a sense of satisfaction from having helped to make the world a better place one pull request at a time. Don’t forget to be grateful for all the help along the way. Open-source is all about community coming together, so remember to give high fives all around.

Keynote countdown timer ⏲

I made a thing!

I was helping a friend with a Keynote presentation deck. One of the tricker parts was that it needed an automatic 30 min on-screen timer to tick down. I’m something of a Keynote wizard, but I hadn’t made a timer before, but I happened upon this great tutorial on how to create one. Timers can be useful for all sorts of presentation types, particularly in classrooms and workshop situations. As easy as the process is to create one, it is quite time-consuming. So rather than do it once and be done with it, I thought I may as well share it.

To that end, here’s my Keynote countdown GitHub repo or you can download it direct. Enjoy.

Github Learning Lab🔬

I’ve been using GitHub for a while now as part of my spelunking into the world of VR and Mobile development. I think it’s fair to say it’s done a great job of protecting me from the inevitable mistakes of learning something new. Having said that, it does take a while to get your head around anything other than the basics.

Thankfully there are a large number of resources available to help you along the way. Most recently I discovered GitHub Learning Lab, a fantastic resource for learning how to use the platform for your own projects or contributing to others.

I think the thing I enjoy most about this particular option for learning is that it’s actually using the tools themselves. Yes, there is text and video to consume, but you actually use GitHub itself to work with the course material. I’m a real learn by doing sort of person so this sits particularly well with me.

So if you’re new to GitHub, or just want to solidify your knowledge of it, I suggest you take a look.