Tag: GitHub

Readme Driven Development

If you’ve ever had a project without a README file hosted at GitHub, you know the recommendation message to create one.  When I first saw that message, I thought it was a bit weird, but, I guess, fine.  It never bothered me enough to search for any explanation – I just ignored it, or created a README file.  Apparently, there is an explanation – Readme Driven Development by Tom Preston-Werner, one of the GitHub co-founders.

By writing your Readme first you give yourself some pretty significant advantages:

  • Most importantly, you’re giving yourself a chance to think through the project without the overhead of having to change code every time you change your mind about how something should be organized or what should be included in the Public API. Remember that feeling when you first started writing automated code tests and realized that you caught all kinds of errors that would have otherwise snuck into your codebase? That’s the exact same feeling you’ll have if you write the Readme for your project before you write the actual code.
  • As a byproduct of writing a Readme in order to know what you need to implement, you’ll have a very nice piece of documentation sitting in front of you. You’ll also find that it’s much easier to write this document at the beginning of the project when your excitement and motivation are at their highest. Retroactively writing a Readme is an absolute drag, and you’re sure to miss all kinds of important details when you do so.
  • If you’re working with a team of developers you get even more mileage out of your Readme. If everyone else on the team has access to this information before you’ve completed the project, then they can confidently start work on other projects that will interface with your code. Without any sort of defined interface, you have to code in serial or face reimplementing large portions of code.
  • It’s a lot simpler to have a discussion based on something written down. It’s easy to talk endlessly and in circles about a problem if nothing is ever put to text. The simple act of writing down a proposed solution means everyone has a concrete idea that can be argued about and iterated upon.

Consider the process of writing the Readme for your project as the true act of creation. This is where all your brilliant ideas should be expressed. This document should stand on its own as a testament to your creativity and expressiveness. The Readme should be the single most important document in your codebase; writing it first is the proper thing to do.

Stash – privately hosted Git repositories

As far as I am concerned, GitHub is the king and queen of applications in the git world.  But it has a downside that is not easy to work around: GitHub Enterprise is expensive.  Keeping code on GitHub infrastructure is not always allowed by authorities and such, and then things get really expensive.  That’s where, I think, Stash can come in.

Stash is a product of Atlassian, the same company that owns Jira, BitBucket, and a few other well-known developer tools.  Given that Stash has only been launched this year, and judging by the screenshots, GitHub probably provides more functionality.  But as I said earlier, GitHub’s price might be simply too high for some companies.

It’s also worth noting that both companies have recently received large investments (Atlassian got $60 million and GitHub got $100 million).  Since private repositories and in-house installations seem to be the primary source of income for both of them, I’m seeing a revved up competition between the two in the nearest future.

OneAll Social Plugin for WordPress

OneAll Social Plugin for WordPress

In addition to the usual suspects of Facebook and Twitter, this one seems to also support GitHub, LiveJournal, WordPress.com, LinkedIn, and a few others.

GitHub compromise : lessons to learn

GitHub has been compromised.  That, by itself, is important enough – with millions of projects and developers using it.  But there is more to it.  Have a look at these links:

There is more coverage all over the web, but I’m sure you know how to find your way around.  Now, to the lessons that we can learn from what happened.

  1. “Don’t panic” in big friendly letters, courtesy of Hitchhiker’s Guide to the Galaxy.  It’s obvious something out of the ordinary happened in GitHub’s routine life.  While they regained the clarity of mind pretty fast, they were caught off-guard.  Don’t panic is the first rule of panic situations.
  2. Pay attention!  Given the size and active lives of both GitHub and Rails, it’s difficult to pay attention to every little detail.  But you should always weight the “large number of installations” or “large user base” considerations.  Even if there is an issue with a documented feature.  We’ve seen examples of this again and again – something that was a part of original functionality once in a while is turned into a malicious attack vector.  Your answer shouldn’t be the simple “check your code”.
  3. Stay transparent.  As you can see from a few comments in the above links, the actual compromise is not the biggest deal.  People in general and software developers in particular are very much used to security issues in every software.  It happens.  The bigger deal is, of course, how you handle that.  When you obviously have a problem, don’t try to hide it or misinform people who rely on you.  Say it loud and clear.  Or you will lose trust.
  4. Mind the stack.  Today’s computing world is rather complex.  Most projects rely on third-party libraries, tools, and solutions.  And that’s a good thing.  But when you do that, don’t treat the third-party item as a black box.  That is especially frequent in Open Source Software development.  It’s easy to trust something that is open.  It’s free, it’s open, it’s secure and reliable.  Not always the case.  And sometimes it is the case, but you need to read the documentation and think carefully.  As much as you are concerned about the security of your own code, there is no guarantee that the libraries, framework, or even the language compiler that you are using are secure.  Keep that in mind.

With all that, what’s my attitude to GitHub now?  It’s still the same.  I love the service and I trust the company.  Everybody makes mistakes.  Not everybody learns from them.  When things like that happen, I’m always willing to give a second chance (and sometimes even the third).  Maybe I’m just hoping that when I screw up people won’t just turn away.  Maybe I’m just an optimist – who knows.  But GitHub still provides the service that I enjoy using.  No matter the compromise, I (or any of my projects) haven’t been affected.  And I think that GitHub will learn from this experience.  So I don’t see any reason to change my attitude.