Monday, October 12, 2015

How Would I Make GitHub Better?

GitHub is an amazing service. It revolutionized social coding. As it has matured, some warts become apparent. It still gets the job done but there are some parts where it could do better. Just the fact that it's so popular will keep it popular for a long time to come unless something radical happens. That's the way it goes in web business.

There are alternatives, such as Bitbucket, GitLab, and Kiln. It's hard to see any of these usurping GitHub anytime soon, though. Of course, thanks to the nature of Git, moving between the systems isn't that hard. You can, for example, benefit from the free private repositories of Bitbucket. GitHub's pricing starts to hurt pretty fast, especially if you have a lot of private work. GitLab is nice if want something self-hosted. And Kiln has Spolsky behind it so that goes some way.

I have several gripes with GitHub. Some are minor and likely very fast for GitHub to resolve should they want to. There are also some structural issues I'm not particularly happy about. I'll try to illustrate my problems next and show existing solutions where they exist.

Starring is Too Limited

I like to mark interesting repositories with a star (1.7k stars given so far). Obviously, once you have starred enough projects, it becomes counter-productive. Ideally you should be able to filter based on project meta information. GitHub allows you to attach only project site and description to a project. No tags are supported. Of course you could say it's better to deal with this within the repository itself (i.e., package.json). That feels too low-level, though, and cannot be used for queries trivially.

There are solutions, such as Astral, that address this problem. I do wish GitHub allowed people to attach more meta information to their projects, though. This brings me to my next gripe.

Limited Control Over Your Portfolio

Once you hit a certain amount of projects under your personal account, it starts to work against you. Just look at my listing of repositories. How can you tell which repositories have good stuff in them? If there was more metadata available, it would be possible to filter better at least. I know GitHub tracks repository language automatically. Having a language filter would be a start.

A good next step would be to allow more control over the way you display your repositories to the public. Perhaps you might want to hide some of them altogether. At the very least it would be nice to mark a select few so that they stand out more.

Given your GitHub account works often as your code portfolio, having more control over it would seem like a no-brainer to me. Obviously you could develop something custom on top of the GitHub API. Perhaps there's something like Astral but for portfolios.

One way to deal with the problem is to push bigger projects below organizations and deal with it there. This won't work always, but when it does, it's a nice way to split up your work and collaborate with other people.

No Pull Requests for Wikis

It is nice that GitHub provides free wikis for projects. In fact, I built jswiki on top of this idea. To allow people to contribute I made it open for modifications. Of course this means some joker might mess up the wiki content somehow given there are no controls against this. Ideally you should be able to accept pull requests against wikis.

It is possible to work around this issue by maintaining your wiki content at your project repository, keeping the wiki closed, and setting up a script that copies the content there. It's not ideal but it works.

No Revision History for Issues

Even though GitHub's issue tracker works amicably well for many purposes, there are a couple of major flaws. Most importantly it doesn't keep track of changes made to the issues. Sometimes it is important to see what the issue description looked like in the past. You can of course dig this information from your email provided you have subscribed to the issue. It's not ideal, though.

The ideal solution for me would be to have the issues available as a Git repository. This is the way the wiki works after all. The repository would track issues and associated comments in some simple format (JSON/YAML?). Besides providing revision history, this would make it possible to maintain the issues through a CLI without having to jump through hoops.

Issues Can Be Removed from a Project Without a Warning

Project issues are behind a checkbox at project settings. Simply unchecking that you will deny access to your project issues. I don't approve with this design decision as it can be quite perilous for open source projects. At the worst you are losing hundreds of hours of effort just like that. Only the parent project retains references to the issues and once they are gone, they are gone.

There's not a clear solution for this. I suppose someone could whip up a service that would backup issues over GitHub's API. Of course, I would rather see this resolved on GitHub's side somehow.

Issues Can Devolve Into +1's

Often people like to drop by issues of popular projects and do a little "me too" kind of reply. As a result you end up with quite long threads sometime with low signal to noise ratio. In addition you end up annoying the project maintainers. Ideally GitHub should allow people to +1 an issue simply by hitting a button somewhere. That would allow the maintainers to see where to put their efforts clearer.

Github +1s Chrome plugin solves this issue partially. It will collapse the +1 comments and show them on top of an issue. The issue subscribers will still receive mail when someone +1's an issue, though.

No Clear Way to Find the Living Fork

As projects develop, sometimes the originating repository simply stops developing and a fork will pick up the torch. Currently there's no easy way to find it. Ideally GitHub would show the most notable forks at the root project page. I know there's network information but I feel it's a little hidden.


I still like GitHub as a service and it's hard to imagine developing without it. I believe it could become significantly better with a little TLC here and there. Not all of these gripes are easy to fix. I do hope GitHub will continue improving as that would be in everyone's interest.

Friday, July 31, 2015

SurviveJS - Webpack and React v1.5 is Out!

The book project keeps on progressing. It managed to attract an editor. You could say that sped things up considerably. It is very useful to have another pair of eyes to push you further and I think it shows in this release. We just reached an important milestone with v1.5 release. The book is structurally much better and easier to approach. Get started by checking out the introduction.

Monday, July 13, 2015

On The Economics of Ebook Publishing

Authoring SurviveJS - Webpack and React has taught me quite a few things. Being a first time author it mistakes have been inevitable. But in some ways I've gotten really lucky. For instance I've gained awesome contacts and received numerous external contributions that have helped to boost the quality of the book. On the flip side as the content is freely available it has been hard to capture value and actually make this financially viable for me. I go into more detail at a little post I wrote under title SurviveJS - The Story So Far. See also Balancing between open and closed publishing.

Publishing is Changing

The world is changing in sense that it's very easy to publish something now. You can even skip traditional publishers altogether. Publishers such as Leanpub provide a hefty royalty. For instance Leanpub takes 10% + $0.50 per transaction leaving the rest to you. With a big traditional publisher you may expect a 15% royalty. If you do the math you can see you would have to sell a lot of book using the traditional way to reach the same income.

The downside of doing it all by yourself is that you'll have to take are of marketing, sales and editing. Leanpub just takes care of the annoying VAT bit. Especially given due to the EU VAT changes made at the beginning of this year things just became more complicated if you want to sell yourself. In effect you'll have to figure out where the book was bought and apply VAT based on that. It's better to let someone else to handle the bureaucracy at least when you are a small player.

It is important to note that Leanpub allows you to publish through other channels. You could sell the book through Amazon or iBooks for instance. Leanpub should probably be thought as an experimentation platform. It will allow you to publish a work in progress book, gauge the interest and develop your book based on the feedback. There have been cases where a traditional publisher has picked up the finished book as it has been shown that there's significant demand for it. It is an excellent value proposition for them after all. Just pour money.

Closed vs. Open Content

One of the biggest questions when it comes to publishing is how to deal with the content and pricing. You could go the traditional way, keep it all closed and put it behind a paywall. This model has been proven to work. You will have to be strong at marketing and get the right message at the right people but it is doable.

Another way, which I chose for my book, is to keep the content freely available. I did this through GitHub. The surprising benefit of this has been the influx of external contributions. You can definitely receive errata in a closed model as well but it feels like an open model is more conducive to collaboration. At times I have felt more like a shepherd rather than a author but I suppose that's a good thing.

As the content is freely available it has enabled more people to get exposed to it. It is always heartwarming to see a positive mentions about the book. Unfortunately this hasn't translated into sales but at least I know I have made a difference for some.

To encourage people actually to buy the book I decided to play on laziness. The digital version available through Leanpub has a minimal price set. I am not giving it out for free. You can definitely compile a digital version of your own but it's always a hassle. I'm afraid having this little hurdle in place isn't quite enough, though. The sales have been mediocre at best and if things continue this way, it's simply not financially feasible to keep it up.

Setting the price of the Leanpub version to zero might not make much of a difference. Perhaps more people would get it through Leanpub then but I'm not seeing the point at the moment. I feel the minimum price of $15 feels fair for a solid book.

As a Finn I cannot ask for donations directly due to legislation so there has to be some intermediate in between. Leanpub allows me to avoid breaking the law.


Given the content is free to begin with the big question is why would you pay for something that's free? There are reasons why Kickstarter, Patreon and such work. Going the inverse way doesn't feel like a feasible approach at least based on the current experience.

This is something I have to find a good answer for. I could start developing commercial content on top of free one for instance or go completely closed. If you have any insight on the topic, I'm all ears. There are likely models that can work but now it's looking a little grim.

Saturday, June 27, 2015

SurviveJS - Webpack and React - Ebook Available

Just a quick heads up. The Webpack/React book I've been working on for a while is available now. Check out for more information and free online version. I hope you find the book useful.

So far it has been an interesting experience and some people have actually bought the book. I can only hope it's providing enough value to warrant that. Now the plan is to see how sales go and perhaps do some careful PR moves. This will determine how I will progress with possible further development.

I wouldn't mind continuing this sort of work as it has provided a refreshing break from the daily grind. But there are certain financial realities to keep in mind. Anyway, we'll know more in a few weeks I think.

Thursday, June 4, 2015

Antwar 0.5.0 - Taking Static Site Generation to the Next Level

As you might remember based on my earlier posts I'm currently working on a book about Webpack and React. Knowing me you understand I like to do things the hard way. In this case it meant writing a static site generator for developing a site for said book.

Given the generator, Antwar, has been developed using these technologies it has been time well spent. The project just reached a major milestone, 0.5.0. It's halfway there so to speak. It's already showing signs of usefulness and it can only get better.

You should check out my post about the release and our plans for the tool. My next personal goal is to adapt the tool to allow me to develop nice looking sites for various projects of mine. Eventually I should get this blog over there.

Tuesday, May 26, 2015

SurviveJS - Site is Up!

I've been developing a static site generator known as Antwar for a while with Andreas Eldh. The project is based on Webpack and React. Two of my favorite technologies. We started from pioneering efforts of Brad Denver and have progressed quite far from that.

As I needed site for my upcoming book and I have to build some momentum behind the release, I decided to build a little site around the content. This was the perfect excuse to push Antwar further. The current development version is more than just a blogging engine. Now it supports multiple sections and uses versatile data mapping (ie. for book content). We'll fold the functionality I developed for the site in the next major release.

To see what can be achieved using the technology, check out I know there are a lot of smaller issues to fix but sometimes you just have to get something out. Perfection can be attained later. I hope you enjoy the online version of the book. There are some interesting times ahead.