01:12 - MIKMIDI

02:17 - Adding Features or Changing the Way a Library Works in an Open Source Projects

04:49 - Deprecation

07:23 - Deprecation vs Replacing

09:37 - Semantic Versioning

15:14 - What is a breaking change?

17:51 - Choosing Issues and Bugs to Tackle; How long should it take?

24:31 - Maintainer Responsibility

26:33 - Being a Good Contributor; Documentation & Examples

31:01 - Using Badges

32:12 - How Travis CI Integrates with an Open Source Project

35:22 - Hosting for Open Source Projects

36:37 - Generated Documentation

39:07 - Licensing

40:56 - What’s changed in MIKMIDI? (Since Episode #57)

Picks

The Big Star Story (Jaim)
Searching for Sugar Man (Andrew)
Erica Sadun: A handful of Swift style rules #swiftlang (Andrew)
appledoc (Andrew)
jazzy (Andrew)
Toastmasters (Chuck)

 

Hey everybody and welcome to episode 131 of the iPhreaks Show. This week on our panel we have Andrew Madsen.

Hello from Salt Lake City.

Jaim Zuber.

It’s been raining here for three days; I’m not sure how people in Portland deal with this.

[Chuckles] I’m Charles Max Wood from Devchat.tv. This week we’re going to be talking about MIKMIDI and maintaining open source libraries. Do you want to give us a rundown, Andrew, of what MIKMIDI is and what it’s about? I know we did an episode on this so a summary’s probably enough.

So we did do a show about MIKMIDI. I think it’s been about a year ago – episode 57. This is a framework that I wrote as part of my work at MixedInKey but we open sourced it. Originally, it was all about adding support for MIDI devices to your Mac or iOS apps. So if you want to hook up a MIDI keyboard or a DJ controller or something and do something with that in your app, MIKMIDI would let you do that.

Since that time, we’ve done a lot of work on it. We’re using it in more of our own apps and I’ve gotten a good feedback from other people using it, and we’ve expanded it to encompass all of the stuff that you do with MIDI. The big stuff that’s been added is support for MIDI files, so loading and saving MIDI files as well as doing recording, playback, MIDI synthesis and that kind of stuff so it’s gone far beyond just device connection and communication.

Since we had people using it, there have been some things that we had to consider and doing a

major update because people already have the code and are using it.

So what do you keep in mind in an open source project when you are adding features or changing the way a library works?

In some sense, you have to take the same kind of perspective that, for example, Apple might take where you don’t want to release an update that breaks a bunch of existing stuff for people; they update to your new code, they get the cool, new stuff you added and meanwhile all the stuff that they were already using is broken or changed, or they got to go rewrite a lot of code because you’ve completely redesigned the API.

So you have to be aware of – sometimes you might want to make a change to an API but you got to either figure out how to do that without breaking it for existing users or you just can’t do it. That can be a little bit tough and I think it also adds somewhat of a testing burden because you need to test to be sure that you're not going to break existing stuff. It’s all a little more complicated that if you're just developing, just writing code that only you are using and nobody else sees or cares about changes to.

Huh. I guess that’s true. I’ve done some open source stuff but I tend to mostly – I don’t usually make that many breaking changes and where I do, sometimes I’ve actually been tempted to say original method or original call, and then original call the better way or something where it’s ‘hey, there is a better way to do this’.

But I have added some of the open source libraries that I have maintained in the past. I haven’t actually added APIs that do the better thing alongside the old APIs because somebody who’s using it, if they want to upgrade it, I want to give them some path and so deprecate the old way and give them some new way that does it better, faster – whatever.

Right. The important thing is not necessarily that you can’t ever change anything and do new things that are better; you just – you do need to give users a good and clear path so that –. If their experience is they pull your new code and they try to build with it and it just doesn’t even build, they just get a bunch of compiler errors, that’s pretty bad. Even worse would be no compiler errors but stuff just doesn’t work right anymore.

So the approach that we took, and luckily it’s one that the tools support pretty well – Xcode and compilers support pretty well is you can actually mark methods as deprecated now. There are APIs as deprecated and then update their documentation to say that they're deprecated and also to tell whoever’s reading this what the new way to do things is. The advantage that that has is they’ll get warnings that they're using deprecated API but nothing will break; if they want to go fix those warnings, it’s pretty easy to look at the documentation right on Xcode and see what the new API is.

So my usual response to the deprecation warning is just to turn off the warnings. Is that how I’m supposed to do it?

Exactly!

That’s exactly what we want you to do. So then in our breaking API really is where we actually finally remove the deprecated stuff then you can just get compiler errors instead.

Alright. You’re fine until you fall off the cliff then. Alright. [Crosstalk]

Yeah, but speaking more generally, because Apple has deprecated APIs too. They deprecated APIs between releases and sometimes I think you do have to make somewhat of a call on whether you're going to replace all that right away because I think updating to a new API means thoroughly testing and can sometimes be a major rewrite. So I would say turn off the warnings but I think deprecation warnings are one kind of compiler warning that occasionally there’s a legitimate reason to ignore at least temporarily.

Yeah, definitely. I’ve worked with a number of apps that haven’t been touched in iOS release or so. Those warnings are there and we’ve made that want to touch them just yet because you don’t know what that part of the code is doing it’s not working.

Getting more on topic, how do make a decision whether you want to do a deprecation – with this release, did you keep the API the same or did you iterate on it, create some new things that deprecate? What was your approach there?

It was interesting because some of the stuff in this release we had – for better or for worst we have released it in the previous release and marked it experimental, told people that ‘hey, we’re still working on this; there’s some useful stuff here but we’re not done with it.’ As we continued to work on that and really fill it out, there were choices we had made early on that obviously were wrong. We just decided we couldn’t design the API that way so we did actually formally deprecate some of the stuff that was in the previous release.

We were lucky that with very few exceptions; the stuff that we deprecated was pretty easy to just rewrite internally so that it called through to the new stuff and did not break existing users’ use of it at all. It wasn’t something that we took lightly because I knew there were people that are actually using this in real apps. I didn’t want to make life hard; I think it’s a sign of a poor quality project if you're not taking that care.

Okay. By deprecate, you mean remove functionality, not just flag it as something that might get removed in the future?

Oh no, I mean we did not actually remove any API. By deprecate, I simply mean we just marked things deprecated so that they’ll get a compiler warning and there’s some documentation saying, “Hey, we’re going to get rid of this is the future; you should remove it.” Nothing was actually removed such that it could not be used at all anymore.

Okay.

How does that work versus replacing something? So you replace something that maybe has the same signature, so it takes the same arguments or generally at least looks the same but may work a little bit differently. How do you determine whether you're going to replace something or deprecate it in favor of another way?

My personal feeling is if you're not going to – if the external API is going to stay the same – a particular method, name and arguments are the same, it’s fine if you rewrite that internally but it should not break valid existing use of it.

It’s fine to completely rewrite, and that’s one of the whole advantages of object-oriented programming is encapsulation so that you can make any internal changes without breaking existing external use of that code.

So there are a lot of examples of that where we changed the way something was done internally, completely without breaking – without changing the external API at all so you can’t even tell that it was rewritten internally; it still works the same from the outside. In some cases, that was because we were just refactoring code and wanted to do things is a cleaner, better way. In other cases, we were fixing bugs and I think fixing bugs is a pretty legitimate reason to even change behaviors. Say you fixed the bug but if it was just truly a bug, I don’t think users expect you to keep your bugs most of the time.

Right. So as long as it has the same expected outcome or the same expected side effects, the same expected return value – if all of those things hold out then you can do more or less whatever you want inside to make it better.

Yeah, right. Another thing I would add to that is when I’m doing this kind of release subject on other projects, I try to be really clear about documenting all that. So I wrote – for this release, there’s a pretty big change log that tells exactly what APIs were added, what were changed. Does the bugs we fixed, and especially the stuff we deprecated in – as much as possible, that stuff’s crossreferenced to the issue tracker on GitHub so you can – if you want to know more about something or see the actual code changes we made for giving change [inaudible] and we can look at that.

My goal is that if somebody really cares or needs to dig deep on any of these stuff, the information’s all there.

you highlighted one problem of creating new functionality or making changes to your library. How do you communicate these with the user? One approach that you’ve mentioned is doing a Read Me saying this is what we changed, this is what might be deprecated. Did you use any versioning to [crosstalk]?

That was what I was going to ask so [chuckles] good question.

Right. So we tried to follow the semantic versioning system. The last release was 1.0 and we’re calling this 1.5.0 which is I think is a slight corruption of semantic versioning because I think depending on who you ask, this maybe should’ve been a 2.0 because we deprecated API; my feeling was it was a major release but we did not actually remove or break any APIs so 2.0 – it doesn’t need to be a truly major version bump.

One things that does is as long as you – particularly in the Cocoa ecosystem, if you tag your stuff properly and, for example, are using CocoaPods or Carthage; those systems will allow you to specify which version you want to use. If somebody doesn’t want to update to this new release and they are already using 1.0, it’s very easy for them to stay there as long as they need to.

Semantic versioning is something that everyone understands until they actually have to write a library where people are depending on it. [Laughter] Would you find out pretty quickly?

Yeah, this is especially poignant in NodeJS because NPM actually expects and tries to enforce semantic versioning. So when people get it wrong, it really screws them up. [Crosstalk]

Yeah, and I actually thing –.

[Inaudible] like the different levels. So semantic versioning, you’ve got three numbers which those will overlook because they want ‘or’ sometimes, but you have the three numbers. And you talked about a 2.0 versus a 1.0, how do you make that decision? Or 2.0.0 versus [inaudible] one, how do you make that decision?

Well, if you actually read the documentation for semantic versioning – this is just some guy that came up with this, like so much of technology. [Laughter]

So much of programming. Yeah.

Yeah, everything is basically some guy.

Some developer.

[Chuckles] Right. It’s now widely used but the idea is that you have three version numbers and the first one is the major version number, the second one is the minor version number, and then the third one is the patch number. The way you increment them depends on the changed you’ve made in your library or app or whatever. You increment the patch, so you go from 1.0.0 to 1.0.1 when you just make bug fixes that don’t affect the external API at all and [crosstalk] the assumption is –.

Or clean up per factoring or anything else like it.

Yeah, but it doesn’t change – from a user of the code’s perspective, they don’t need to care about any of the changes you made, just ‘oh hey, it’s better. Got bug fixes but I don’t need to do anything’. But of course, if you're going to do that then you got to be really careful that you're not making major changes because some systems like – you mentioned NPM Chuck but I think even CocoaPods is depending on how you’ve set up your pod file. You can tell it to automatically pull patch versions without pulling major or minor versions. I think that’s true.

Yeah, the pod file in CocoaPods is based loosely on RubyGems and Bundler.

Yeah right.

And yeah, it’s the same there. You can specify a specific version or you can specify that anything above the patch, minor or major version number that you’ve put in there is acceptable.

So the minor version is when you make changes, not just bug fixes but you – well, semantic versioning says you add functionality in a backwards, compatible manner. So you're making changes; you're adding new stuff but you're not actually – you're not breaking things for existing users. Then the major version is when you make breaking API changes, so you make changes that mean that existing – users of existing versions can’t just upgrade and expect things to work without changes.

Turns out it’s a little bit more complicated than it sounds because technically this release I just – we’ve been talking about is just a minor bump from 1.0.1 to 1.5.0. Technically, I did not make some breaking changes but I did add the [inaudible] methods. You’ll be at warnings but not errors and whatever gray areas. [Crosstalk]

Yeah, but deprecations aren’t breaking changes.

Yeah.

They're just warnings that things are going to change.

Right, I won’t remove any of these stuff until version 2 at least.

I think you should jump from version 1.5 to version 10.

Like Note did from version 0.something to 4? Whatever that was?

Yeah. Well, there’s a bit of story behind that. They adopted the versioning of io.js which split off from them and when they came back together.

Yeah, I actually knew that.

But anyway, why did you bump from 1.0 to 1.5 instead of 1.1?

Well it’s funny. The branch that we developed all this new stuff on was 1.1 and it was called 1.1 until the minute I released it. But it was just clear that – this is probably a problem of management for us, but what we thought was going to be a minor bump got bigger and bigger and bigger as time went on and took longer and longer and longer to finish. When we were finally done, which was just about – I actually think it was on a Saturday that I did this, so like four days ago as we record. It was like we were adding way more stuff than I expected to add for 1.1 so I called it 1.5

just to convey the fact that this is a big deal.

So if you get someone who asks ‘where is version 1.3?’ You just say it’s [inaudible] work on Windows 9.

Yeah, it works on Windows 9. Yup.

The changes between 1.3 and 1.4 and 1.5 are really, really, really small.

I could go back and make fake tags for them, right?

Yeah. Nuts, [Chuckles] Anyway, that’s interesting, and it’s funny too because then you get into what is a breaking change. So some people consider a bug fix that actually changes the behavior that people might’ve relied on as a breaking change and other people don’t. In those cases, the people who don’t would advance the minor number and the people who do would advance the major number. So you go from 1.0 to 2.0 instead of 1.0 to 1.1.

And to be honest, we’re not at the point with this framework where we have enough people using it that we probably even know about those kinds of bugs.

Yeah.

Because I don’t really know what people are having to work around, but for a really big vendor like a platform vendor like Apple or something, I know that they do that. There are bugs that are in Cocoa and they're pretty widespread that people are doing specific things to work around those bugs and rely on the fact that the bugs are there; if they fix the bug, they actually break things for people so they don’t know; they go out of their way not to fix them. We did not do any of that but that’s a hard question; how do you really answer that?

Yeah, and I think there is some consideration to that, too. Am I affecting hundreds of people or tens of people or thousands of people?

Right, and I don’t know. We’ve got about a hundred stars on GitHub and a few hundred installs on CocoaPods so it’s [inaudible] affecting millions of developers or anything.

You’re a hundred air.

I’m a hundred air.

Well, with semantic versioning you at least give the user the library, the power to decide what they want to happen because depending on the phase of the software or the application, they might want completely different things. If you're working on something all the time, you’re developing an app, you probably want the bleeding edge stuff always. As soon as you can get it, you do your pod update, you get the new stuff. If you’ve got a mature piece of software that’s been around for a while, you might want to walk down the versioning. You’ve noted the path version just to not having a risk of it updating then you give the user the power to do things in between, because if something is not being used a lot, you don’t want to invite little changes that can break stuff; you just want to lock that thing down.

Yeah, and that doesn’t mean you never want to update but it means that you have control over it so that when you decide to update these dependencies, you do that when you have time to test and make sure that things did not break and make changes if you need to support the new stuff or whatever. To me that’s a pretty important part of being a good citizen as far as putting code out there for other people to use.

If I want people to take this seriously and actually want to use it, it needs to not have huge downsides and things that actually get in the way and cause problems.

I want to change topics on this a little bit. This is fun to dig in to why and what you would do for open source. One other question that I’m wondering about is how do you decide which issues you're going to fix first or which bugs you're going to tackle first?

Related to that, I am also curious what both of you think about how long it should take for an issue to get taken care of.

I’ll answer that question for myself – for this project in particular. I think our prioritization was bugs that affect us are highest priority, because we’re writing this code; we’re using it in apps that we’re shipping and making money on from MixedInKey and MixedInKey is paying me while I’m working on it. So obviously, those bugs are the most important. I can’t really prioritize people who are not paying anything over the company paying for the code.

You folks are so mercenary.

Yeah. It turns out we’re probably using this more heavily than anyone else because the API here is all here – are almost all here because we need it so we’re probably finding most bugs before other people do. But then the next obvious thing is bugs that have been reported by people and especially by more than one person are the obvious candidates.

Further, a bug where there’s a typo and something that gets printed out to the console or something – who cares? You're sure you want to fix that but it’s not going to cost any real problems, but a bug that’s causing a crash or data corruption, you're going to prioritize those higher.

Would you prioritize a security bug over something that MixedInKey is using heavily?

Yeah, probably so although I’m not sure – there’s always room for security bugs to creep in but I’m not sure what we’re doing is terribly bad that way; it’s not a credit card processing [crosstalk] framework.

That’s true. I was just thinking in general if it was a security issue versus we don’t really use that API in house but we know other people outside use it, and we’ve got a major bug that affects us and the other major bug that affects people using that particular API in opening up a security vulnerability.

My first thought not having to actually deal with that situation, my first thought is a security bug, especially depending on the security, that has the potential to impact people in a really pretty terrible way so that’d be an important thing to fix.

Yeah, and it does affect your corporate open source image et cetera so it is a big deal.

What do you think, Jaim? How long should it take to fix bugs that people report?

That depends. Is someone paying you to fix that bug? [Crosstalk]

Assuming the answer’s no.

Generally not. [Crosstalk]

I was going to say ‘this is open source’ [crosstalk] so assuming the answer’s no.

But a lot of open source is sponsored by some companies; you're project is worked based on something that your company had done, so if it didn’t work for someone else, it might show up in your code. For libraries, I’m lucky enough to have some type of sponsorship where people are working on things and that’s part of their job and they can fix it.

I think one of the downsides of open source is getting to the mentality that someone owes you this software; you didn’t pay for it, you didn’t do anything to make it come and do this [inaudible] but they need to fix it right away. A lot of these libraries are some developer doing these things on their free time – you don’t have to work on weekends.

I think it’s important to state that be a good citizen; if you filed a bug report, it may not get fixed especially if you’re doing some – you're some obscure level of that library. Just be knowledgeable that people are doing this out of their own free will and generally not getting direct monetary compensation for it.

I would say, if part of your goal of creating a library is having people use it – if something is not working right, you have a security bug and you want to fix it and that’s part of why people do open sources; they want their stuff out there to be used. They get some good feelings out of that.

So if you have the bandwidth and you're getting enough out of it then definitely go and fix that stuff. I wouldn’t have a whole lot of patience for someone if I worked on a project, put it out there and then keep [inaudible] me to fix this bug that they're working on like ‘okay, well I’ve got other things to work on now’. That would work too well with me.

I kind of come down to where you are Jaim; I think I might state it a little bit differently. Again, if it’s a high severity security bug or it makes the library impossible to use, crashes the app – things like that. I can see some expectation of you fixing it up within a few days to a week or however long it takes to fix it but within a reasonable amount of time. At the same time, it’s open source so somebody else could legitimately trace the bug down for you and submit a pull request. The other thing that I would bring up is that if it is crashing version 1.1.2 but not 1.1.1 then they do have the option of rolling back until you get it fixed up. So there are definitely things now – they have options. If there’s no options and you’re – or it opens up a major security vulnerability or anything like that then yeah, I can see people saying, “Look, this got to be fixed fast.”

But then again, if somebody has life circumstances – their parent is terminally ill or they have some issue – some family issue with a child or things like that, they may just not be able to get to it and I don’t know if it’s reasonable to expect them to drop anything and go fix it.

I have the issue of the mentality that you rely so much on the software that you can’t work around it. When you bring in someone else’s code, there’s risk there and if you're working on this day in and day out, you need to manage that risk. If you're application is completely dependent on this library working perfectly then that’s a whole lot of risk for your software and maybe that’s not the best way you should be writing things.

My thought on this is basically what you already said, but I’m usually not shy if somebody reports a bug. Typically, I’ll say – I’m assuming it’s a fairly low severity but I’m not talking about security or data corruption or something, but I’ll say, “Yeah, I’ll get to this when I can and it’s not necessarily going to be right away, but you’d be welcome to fix it and submit a pull request.”

I want to be balanced about that because there are people who are brand new and they don’t feel like they can or they [inaudible] or whatever. A lot of people, I feel like if you're using this library, you’re already doing something advanced enough, and you're using it in an iOS or Mac app so you know how to write iOS or Mac apps. You can dig in to the code, find the bug and fix it.

I’m also a lot more inclined to fix a bug when somebody’s really good about helping me diagnose it, steps to reproduce and stuff. Occasionally, I’ve had somebody report a bug and then you ask them for more information and you hear nothing back and I think [crosstalk] –.

Let’s not be important.

I’m not going to put too much effort into this if even the person who found it doesn’t care.

I want to just throw one other thing out and that is that I do think that maintainers do have the responsibility to communicate with the people who are reporting bugs. For example, if somebody comes in and they say, “Hey, we’ve got this really high-level, critical bug that absolutely is killing us off,” and the maintainer is, “Well, I’m under a crunch for work or whatever and I am not going to be able to look at any of these for another two or three weeks,” so they should at least let them know that.

For the lower quality – lower severity ones, I got no problem with pushing back for more information and just seeing where we can get to because letting people know where it stands on the priority list and letting them know where you are as far as being able to solve their problem for them at least gives them the opportunity to say, “Okay, well I can either wait a month or I can solve it myself now.”

Yup. We had an interesting – in this release in particular – we’re actually pretty late. Just a couple of weeks ago, we got a really nice guy that I knew was using the framework and he opened an issue saying there’s some functionality – not a bug but a feature he really wanted and he was wondering if we could add that. I said, “Well, I like this idea but I don’t think we can really get to it right now but we’ll try to at some point. If you want to submit a pull request that would be good.”

Then it just so happened that a few days later I needed the exact same feature in one of our apps and I had not predicted that. I couldn’t see it coming so I wrote it, and the fact that he had opened that issue and asked for the feature meant that I know when I went to write it then I wanted to write it into the framework as opposed to being just part of our private app code, and I wanted to make it so that it was nicely designed and generic and it would be useful for more than just us. The fact that he asked for it, it probably would not have ended up in the framework if he had not asked for it which means if you're using an open source project and there’s something you don’t like, do file issues and ask questions because it’s an important part of the whole development process for open source.

Yup.

So what else can people do to be good citizens of library users?

There’s something that I’ve seen and hear that I want to call out. It is definitely something in MIKMIDI that I’m noticing and that is you do have a changed log.md, you got a contributing .md, you’ve got a licensed. So you're communicating with people as far as how they can drop stuff in, you’ve got to change log that shows them what’s been put in there, and the license tells them more or less how they can use it and what the terms are. Are there other things that you feel ought to be in there, or you could just talk about these things that are in there? Why did you put those in there, Andrew?

Well, I actually just added the change log a few days ago finally, but I think these are all essentially parts of the documentation for the project. When I'm trying to find some code that I want to use, if it’s got all of these stuff and it’s clear that it’s a well-managed project and they're thinking about how people are actually going to get started with it; the overall quality tends to be higher. But there are actually some things that are missing things that I want to improve in the next release.

Particularly, I want some more high-level documentation, so I think we’ve done a good job of documenting the code itself and you can look at documentation for it on CocoaDocs and just in the headers, but I want to add a Getting Started guide and here are some high-level explanations of how to accomplish various tasks. The other thing that I think is really important for library – open source library is example code. I’ve got some of that but I want to improve that. I want to have examples of various, different, fairly simply things that show how to use the common, important functionality that’s in the framework, because it can be pretty daunting to look at a library like this which is fairly big; it’s not a small library, it’s not two classes, it’s a hundred or something, and just figure out where you look to accomplish what you want to accomplish. Seeing how that’s actually used in real code is pretty important.

One other one that I’ve seen pretty often is like – I guess it’s in the contributor’s, but it’s a contributor covenant. So basically it says ‘don’t be a’ – I want to say a-hole but ‘don’t be a jerk; treat everybody nicely when you are interacting or contributing to this library’.

Yeah, I should probably add something like that. I don’t – it’s not something I’ve done before or thought about a lot because it’s not something I’ve had a problem with in the projects I’ve worked on but I know it is a problem especially in really big, popular projects. I can’t really tolerate that; to me it sours the whole things because I’m working on this for fun basically because I think it’s fun to work on; I think it’s fun to have other people use it. I get some satisfaction out of it.

If I really wanted to, I could never had open sourced it in the first place and we would be wholly using it ourselves. I think some in-riding enforced in it that we’re not going to tolerate people being jerks and ruining the fun for the people who are working on this. It’s pretty important; I might have to add that.

Yeah, there’s one that’s out there that is a contributor – covenant.org. They have a boiler plate for this. A lot of big projects have adopted it. It’s pretty interesting and it’s kind of a good start at least even if you're not totally on-board with the exact wording. It’s basically an open source contributor covenant that you can use anywhere and you can change to fix stuff up.

They are in version 1.3.0 so I usually point people to that as a place to start, but yeah. For me, I’m in the same place; I’ve never maintained a project where people were being mean to each other or using some overly aggressive tactics dealing with each other. For me, it doesn’t come across as a big deal but I do know that some people look for it before they start contributing just so that they know it’s kind of an open-friendly project.

Yeah, as you get a larger and larger library where more people come in that just – people are being bad to each other happens.

Yeah.

It becomes more of a problem. If it’s a library with a handful of people working, they can figure out how to work things along. If it’s a lot of people then just human dynamics, that’s how things can progress so you have to handle it.

I’m pretty happy; I’m happy to see the contributor covenant so that’s nice. If I have any – released any open source, I’ll definitely would look into this.

Yup. I also noticed that you're using Travis CI on MixedInKey, or at least you have a Travis.yml in there.

Yeah.

But there’s not badge on the Read Me.

Yeah, I don’t know. I thought about putting badges on there.

I just wonder – sometimes I see [inaudible] as ‘oh, that’s cool’ but I don’t know how much value they really had. I was wondering what your take on it was.

Same basically – I kind of have mixed feelings. I think it’s like, “Well, why are you adding these badges? Is it to pat yourself on a back and say –?” [Crosstalk]

I got 104% test coverage!

Yeah, exactly. ‘Look how great my project is’ and that’s why I haven’t added them. The other thing is, to be honest, I only put this on Travis last week. I’ve just been running tests manually but I finally added it to Travis last week so I haven’t even thought about putting a badge on. Maybe I’ll do that but that does bring up a larger point which is that if you're – Travis in particular makes it really easy to do continuous integration so that if somebody submits a pull request or even just you push a change to your repository, Travis will automatically run tests and make sure stuff is not broken. It makes it easier to not inadvertently push bad code into your repository.

So how does Travis integrate within an open source project?

It’s actually pretty easy to set up. You create this .travis.yml, this yml file that tells Travis a little bit about how to build your project. It’s pretty simple; this is actually – if you look at the one in MIKMIDI, it’s actually more complicated than some because this is for both Mac and iOS. So there’s some stuff in there, but if you don’t have that – say it was just an iOS project, basically you just tell Travis ‘this is an Objective-C project’ and ‘here’s the path to the Xcode project’ then Travis will just build the Xcode project and run any tests that you have in there in your unit test target. Of course, when you first set your account on Travis, you give it access to your GitHub account so that it can see your repositories and pull code from them.

I don’t actually know the details but they’ve got hooks back with GitHub so that if you submit – for example, if you submit a pull request, somebody submits a pull request through a project that’s using Travis, Travis will see that pull request, will build the project, run – build the code with the pull requests, run test on it and then it will actually show you the result of the test right in line on GitHub in the pull request. So you can very quickly see if something broke or if all tests continue to pass.

Now is Travis a hosted solution? Are you running the machine on one of your servers?

No, it’s a third party but it’s free for open source projects. [Crosstalk]

Ahh, I see, okay.

It’s free for open source and it’s hosted. This is not the first project I’ve set it up for but even on the very first project. First time I’ve ever used it, it took me five minutes basically to get it up and running. It’s pretty easy.

One of the things that I’ve seen done on Ruby in JavaScript projects, and I don’t know the tool that does this in Objective-C or Swift but there are linters that you can run against it and they will enforce your style guide and things like that.

I’ve actually seen pull requests get pushed in and then Travis runs and it puts comments in. so if you go look at the pull request and look at the particular files, it’ll actually have little comments on particular lines of code saying, “This doesn’t match your style guide. Fix it.”

Oh, interesting. I don’t know if there’s anything like that. I don’t know if Travis has any support for that in Objective-C or Swift projects.

There is a project [inaudible] – a tool called ClangFormat that – I don’t actually know a ton about it but it’s somehow a similar sort of thing for Objective-C and I think Swift now, too, but that might be something that would be nice to add at some point.

Well, what I’ve seen is that they put it into their test run for their projects, and so it just gets run with the other tests and then it gets put in the same way that your test failures get put in on the pull request.

Oh, interesting. I should investigate that at some point because there are plugins for Xcode essentially that will do that. Just when you're working on Xcode, they’ll either reformat or they’ll flag warnings on code that doesn’t match your code style.

Uh-huh. Put that in as a potential topic.

I actually think it would be interesting sometime to just talk about code style and Objective-C. Especially in Swift where some of these style decisions are still things that the community is just now hashing out.

So you're hosting it on – yeah, you’ve got it up on GitHub; is there a reason you’ve chosen GitHub over, say, Bitbucket or something else?

We chose GitHub – I chose GitHub because it’s the most, at this point, the most popular platform for open source projects and probably on most platforms in most languages but certainly in the Cocoa world. To be honest, I didn’t think too deeply about it; I kind of wish Bitbucket were popular because we use Mercurial at MixedInKey, not Git, and Bitbucket supports Mercurial repositories.

Yeah, that’s usually one of the reasons why there are people picking Bitbucket. The other one is they use the Atlassian SuiTest products and they integrate more cleanly with Bitbucket than they do with GitHub.

We actually use Kiln and FogBugz at MixedInKey so we’re not using Bitbucket, but I don’t think Kiln has any support for open source repositories.

Anyway, I’m more concerned with people discovering this and I think GitHub is the best place right now for people to find projects like this.

I also like GitHub’s issue tracker quite a bit. It works quite well for the kind of development I do for open source projects.

For open source projects, I don’t notice any compelling reason to use anything else except GitHub.

Yeah. [Crosstalk] As for people

Performance tools are much better than Bitbucket.

So one other thing that I want to ask about and that is that it looks like you’ve got some generated documentation on CocoaDocs. So how did you pull that together? Is there some process behind that or is it just the way you format your documents?

So this is pretty cool and I actually – I’m not sure I’m the biggest fan of CocoaPods in the world. I don’t use CocoaPods myself but CocoaDocs, which is part of the CocoaPods project is really cool and I really like it.

Xcode for a couple of versions maybe since version 5, or maybe it was even one of the four point something versions, has had support for documentation in the headers that Xcode picks up. By picks up I mean if you’ve documented your code using this comment style and it’s like JavaDoc or Doxygen. You can actually use a few different styles, but if you’ve commented – properly formatted your comments in your code, Xcode will pick it up meaning you can option click on a method and it will show you the documentation for that method even if it’s in your own code.

CocoaDocs is piggy-backing on top of that to provide this documentation. They're actually using a tool called appledoc which is also an open source tool that’s been around for a long time that is specifically – it’s called ‘appledoc’ but it’s not made by Apple, but it’s specifically for parsing these documentations and generating Apple-style documentation for Objective-C code.

Basically, I did not have to do anything special to get it to work on CocoaDocs. All I had to do was document the code using the normal comment style for documentation. Then, you have to put your project on CocoaPods because CocoaDocs is only for projects that are on CocoaPods and you get it for free.

They actually let you customize some of these if you want just in terms of colors and theme for the CocoaDocs site but I have not done that on MIKMIDI.

I like it though because I can send people a link to this and it’s nicely formatted documentation that’s not too different from what you’d find in Xcode. The other cool thing is there’s a documentation called Dash that I think is pretty popular now. It’s not free; it’s a paid app but a lot of developers use it. It’s a Mac app and Dash knows how to download docs set from CocoaDocs so you can really easily get documentation for anything that’s on CocoaDocs and Dash. It’s local on your computer; you can click on something in Xcode and have it open up Dash and see documentation just as easily for MIKMIDI as for UI kit or something.

Alright, one more thing I want to talk about really quick and then we will go to picks, and that is the license; you chose the MIT license. Was there a reason for that?

Yeah, this is sort of a de facto standard or at least for projects for Cocoa [crosstalk] open source stuff but basically, I think the GPL doesn’t really work for most people because they want to be able to use projects and closed source apps and I’m completely fine with that. I want people to be able to use things. I’m not really seeing it because I have this really staunch, ideological opposition to close source software. Obviously, I don’t want to work on close source software all day everyday so I think the MIT license is a nice compromise. You can use this however you want just give me credit.

Yeah, that’s generally what I use to though I have looked at some of the other licenses out there. The Apache license looks nice but it’s really not that much more restrictive. The GPL is usually the complete opposite spectrum when I talked to people of the MIT where MIT says use this however and wherever you want. You can change the code, you can copy the code, you can modify the code, you just have to leave my name on it.

GPL says that if you use this anywhere then whatever you use it in also becomes open source. If you don’t release an open source then the company can actually sue you for violation of their license.

Yup.

Yeah, for a library GPL by itself is not useable because of those things. They do have the LGPL which works around some of those issues.

Some but not all, and it depends on what trade-offs you're willing to make. There’s also the AGPL, the Affero GPL which also works around some of those issues.

We should have an episode on software licenses though. That would be fun, too.

Free lawyer advice. [Laughter] Fantastic. Worth every penny.

From a bunch of non-lawyers.

Yup, but yeah, I tend to go with MIT.

Alright, we’re kind of at the end of our time. Is there anything else that we should talk about with open source? I think we should give you a minute Andrew to talk about what you’ve changed in MIKMIDI since we did an episode on it before.

Yeah, I’d like to do that. I’ve mentioned it a little bit at the beginning. The big stuff that we’ve added is – we’ve added pretty full featured support for doing MIDI playback so you can import them – you can open up a MIDI file and play it and you can do that using the built-in synthesis stuff in CoreMIDI which is pretty bad on iOS and pretty good on OS 10, or you can load your own SoundFont files so we’ve added support for SoundFont files which is the standard way of storing different sounds like piano or guitar, crazy sounding synthesizer or whatever.

We’ve added support for doing recording so you can really easily set it up so that you have a MIDI keyboard hooked up to your app and you want to let the user play into that MIDI keyboard and have that get recorded to a MIDI file. That’s not actually that easy and – just in CoreMIDI. That’s a sequence where we have a pretty full featured sequencer called MIKMIDI sequencer. Around that, we’ve added pretty good API for doing MIDI synchronizing clocks and all that.

On the device connection side which has not seen a lot of changes but we added a connection manager that just makes it easier to implement common scenarios where you have an app that you want to let the user determine which MIDI devices they want to actually use in the app. That can get [inaudible] in as user defaults and automatically saves those connections and restore them when the app relaunches.

There’s a lot of cool stuff particularly around MIDI synthesis and file playback and recording.

Awesome.

And I have to say I definitely want to give credit to Chris Flesner who’s one of my co-workers at MixedInKey. He wrote a lot of the new stuff in this release, in particular the sequencer’s pretty much all his work. He did a really good job with it and it’s pretty cool. I’m impressed with what he’s done – I think we’re both pretty proud of it.

Awesome. Well, let’s go ahead and get to the picks. Jaim, do you want to start us off with picks?

Sure. I’ve got one pick today. So I was browsing on Netflix a couple of weeks ago and I ran across The Big Star Story. Big Star’s a group; they're around the seventies. Weren’t terribly popular but they become very influential later on. They're one of the groups that no one actually listens to when they're around but, as they say, everyone who did started a band. They became pretty popular in the eighties; a lot of the alternative bands in the eighties and the nineties took up the influence from Big Star. There’s a documentary out there on The Big Star Story.

I was a fan of the group before; I had the first couple of albums. I like them but hadn’t really listened to them in a while but – they got me into it but they're great albums. Andrew, you probably know what I’m talking about. They told the story about the band and how they were triumphant with the release of great records that the critics loved and they had terrible distribution but this [inaudible] was not happening for them and no one bought their record; no one knew about it but you can hear the story and it’s an interesting documentary.

I learned stuff about [inaudible] the members. Chris Bell who was on the first album and kind of quite the band, he did some solo stuff later on that sounds a lot like Big Star so that was outside. I was introduced to that through the documentary and did some good stuff but check out The Big Star Story, streaming on Netflix.

I’ve too check that out. It sounds really interesting and up my alley.

Yeah. Andrew, what are your picks?

Well, I had a couple of picks picked out but Jaim reminded me one that’s kind of along the same lines which is probably more well-known than that.

There’s a documentary called Searching for Sugar Man. Came out about two or three years ago – probably three years ago at Sundance but then was in theaters, about a guy named Rodriguez. He similarly was critically acclaimed and sold almost zero albums and basically quite the music business and just worked in construction.

Unbeknownst to him, he was actually super popular in South Africa. The movie’s all about that and how his fans in South Africa rediscovered him and found out he was not actually dead as the rumors said.

[Chuckles] Wow!

And found him just living in Detroit, living a pretty modest life. I won’t spoil the ending but it’s a good movie; his music’s good. I actually got to see him in concert this summer and that was fun. Last summer, I went to the record store in Cape Town that is prominently featured in the movie so that’s a good movie to watch

My other picks are a post by Erica Sadun about Swift style rules. She just put together a handful of Swift style guide type rules but she has collected it from other people but I think this is Swift style or something we’re all still figuring out so I’m interested to see how different people are doing different things. This is a good article that I think just came out today or yesterday.

My last pick is – well, it’s a two part pick so it’s appledoc which I mentioned before is used for CocoaDocs but it’s also something that you can download and use yourself, and it will convert your Objective-C documentation into HTML. Going along with appledoc is a project by Realm, also an open source project called Jazzy. This is the same sort of thing; it’s like a modern – almost like a modern replacement for appledoc. It supports Swift. [Inaudible] just supported Swift but they’ve recently added Objective-C support as well and I think CocoaDocs is planning to move over to using Jazzy but both of these are pretty cool projects. If you're writing open source code or even just writing your own code and you want to create good documentation for it. Those are my picks.

Alright. I’ve got a couple of picks here. The first one is something that I have picked on the show before to be sure. Anyway, I’m really excited. Jaim actually gave me a challenger later to this pick. It’s Toastmasters and I’ve really been enjoying it. I’ve been going since January, and Jaim gave me a challenge when I mentioned that I was looking at going that I should try and get my ‘competent communicator’ within the first year. So I joined up in January and I am giving speech number ten tomorrow as we speak which finishes out my competent communicator and I’m sure excited so I thought I’d share a milestone for me as well as encourage people to go out and get involved in Toastmasters.

It’s turned into more than just going and practicing speaking; it’s a program that involves speaking but it also is a program that involves leadership and things like that. I’ve been getting involved in the leaders in my club and talking to a friend of mine about starting another club. Anyway, overall I’m just super excited to be involved and I think people should go check it out so go check out Toastmasters.

Awesome. Congratulations.

Thanks.

I was a member for five years of a club. Completely helped me out; I was – definitely helping out my career, probably the best thing I’ve ever done. Not just being career-focused but being able to work on interesting things and having people listen to you when you bring up ideas. We used those skills all the time even if it’s in a stand-up or talking to your boss or talking to a client. Plus one.

Yeah, I’m also well on my way for a competent leader. Some of the hard ones on that one are organizing a speech contest which I did,, and being a club officer which you have to do for six months in order to get it and I’ve been filling in there but I haven’t actually completed that but there are a few other things that I’m looking at doing. You have to participate in a club PR campaign or one of the number of other things for another requirements. I’m working on that, but anyway it’s just been a blast.

That’s my pick. I guess we’ll wrap up. Thank you both for being here and we’ll catch everyone next week.