It’s just some scribbles, really, but I’ve heard some people found them helpful, but that was only if they would ever find them hidden away in some wiki. So just in case there’s something in there that might be helpful to you, here they are in their full raw glory.

Communication Rules

• Listen for arguments in discussions, ignore feels. Ok, we need to get this one out of the way as soon as possible: Discussions need to be direct and without bullshit. Critique is the highest good in our OSS economy, so embrace it and try to stay away from defensive comments. We already have plenty of messages to read, so keeping it to functional (and as succinct as possible!) messages will ensure we don’t subconsciously start ignoring you for the amount of noise. It’s harsh, but c’est la vie.
• Be explicit, don’t use anaphoric references.
• Be verbose where it increases clarity, don’t use acronyms.
• Use real-world examples, don’t use variables like ‘sut’, ‘foo’, ‘bar’, or even ‘baz’. Unless you are referring to somebody named ‘baz’, the context is people, and most people know who ‘baz’ is; symbols like these are not self-explanatory.
• Keep asking “why?”. Really understand the reasoning behind a requirement before implementing.
• Assume that somebody is not a native English speaker. Keep this in mind when somebody is not understanding your “clearly defined” sentences and re-phrase accordingly. Also, things like ‘fuck’, ‘deserves a kneecapping’, etc, might be totally friendly where you’re from, but the person you’re communicating with is probably not where you’re from and you might scare them.
• Avoid the use of emoji to convey if a message is well-intentioned. Instead, don’t ever write mean-intended messages. People might read mean-intention into your message, but once you start adding emojis to clarify that this is not the case, then you might have a hard time if you forget to add an emoji the next time. Instead, let’s assume we all have the same intent of improving the project.
• Avoid sarcasm. Sarcasm translates hard without face-to-face body language and is usually taken in a bad way when misinterpreted. This is often accompanied with the use of emoji to covey that no mean-intentention was intended, but, as stated above, emoji meant for this reason should be avoided.

Design Rules

• KEEP IT SIMPLE, STUPID. Do not try to tackle possible future issues until they come along. Do not tackle existing current issues when the issue is a corner case affecting only a few people and the code required to fix it is more than a few simple lines. I.e. the benefit of the change has to outweigh the complexity required, that it adds to the code-base, to fix it.
• Options are the work of the devil. This is always true. You should try to strive for less options, never more. When there’s the feeling that some functionality does not fit in the scope of any other existing option, then maybe those existing options need to be revisited first.
• Keep it lean. Pretty closely related to the above ones, but possibly less obvious to people. Keeping things simple also means not pulling in new dependencies without thinking hard about how to otherwise solve the problem. When in doubt, remember “you do not need another queueing system”.
• User convenience trumps design principles such as avoiding code duplication (DRY). Unless it introduces much much much more complexity than the convenience it provides, the user-experience should always be taken into account first. Avoiding code duplication is not a good enough reason in and of itself to divert the burden to the user of the program.
• Know required details first, then think of how to design and implement. This means that you should not assume to know how a Xcode/compiler/linker issue works, but first manually verify how something works and be open sure to test out different approaches. A solution based on assumptions only is not acceptable, ever. Once you have the data, only then decide the best course to take, always keeping the KISS principle in mind and thus choosing the simplest course.
• Implementation over discussion. Do not keep discussing to reach an implementation. Discussions often contain assumptions and just as often these will be wrong. At some point a bare bones implementation will make further discussion much easier. When doing this, do not feel like you need to have something polished to show to the team, because it should be possible to throw away the code without feeling bad about it.
• Once you are a proven ‘pro’ at X, you may selectively ignore rules. Many of the things described in the list do not always apply in all cases. The key here is that as a ‘pro’ you should know when it’s ok to make an exception and you should be ready to defend your decision with fact based arguments, otherwise you will fail to get it passed our scrutiny. Once you’re a ‘pro’ at X, it’s perfectly ok to use hyperbole to make things clear for the general case (i.e. on tickets as well). Some people need to be told in direct terms before accepting that path X has been tried already.

It’s part of your app.

At runtime, whether or not code is specific to the app or lives inside a 3rd-part dependency is irrelavent to me. If you decide to pull in a dependency, be it explicit or implicit, then, in my book, you’re on the hook for maintaining it.

Checking the sources of 3rd-party dependencies into SCM makes for a great way to review the sources we’re pulling in and to be aware of the sizes thereof.

Don’t trust the internet.

If you’re trusting that sources you depend on can be hosted elsewhere out of your control, then sooner or later you will suffer. Sources will go down temporarily or even indefinitely.

Checking in sources is akin to backups. Backups are good. I know this, you know this, even if we don’t make any backups of our personal data.

Simplify bootstrapping.

Not every contributor will need to manage dependencies, especially not when first checking out your project. Minimizing bootstrapping steps will make them happier and more productive. Imagine if those contributors aren’t even developers, but for instance designers… ugh, that must suck for them.

Checking in the sources you depend on and setting up the project to be able to run without the dependency manager even being installed is the best experience you can give your new contributors.

But checking in dependency sources adds noise to my project sources.

One popular solution among believers of checking in your dependency sources is to have a dedicated external SCM module for these. Then the diff of your project will simply show that the external dependency module changed, so you’ll still be able to connect dependency changes to project changes.

At Artsy we have an external repo for our CocoaPods dependencies.

It’s perfectly fine of course to do whatever works for you, but it’s important to keep in mind that official recommendations in documentation are generally made for good reason. So here’s two other ways in which a conversation about bootstrapping your CocoaPods project could go.

I’m not going into CocoaPods VS other dependency managers. I will, however, say that there’s plenty of valid things to complain about with CocoaPods, but making bootstrapping harder on yourself is simply not one of them.

Bootstrapping a project that checks Pods in.

We’re using CocoaPods to develop this project and have checked in the sources as recommended in the CocoaPods docs.

Cool. What do I need to do before I can run the project?

Nothing, just open the workspace and build.

Wait, I don’t even need to install CocoaPods?

Nope, not unless you’re going to be changing any dependencies.

Neat.

Duration: 0.

Bootstrapping a project that requires installation.

Install CocoaPods. You can find a link to an app that bundles all tools you’ll ever need on the https://cocoapods.org homepage.

$ time curl -sOL ‘https://github.com/CocoaPods/CocoaPods-app/releases/download/1.0.0/CocoaPods.app-1.0.0.tar.bz2'
 12.31 real 0.13 user 0.28 sys
$ time tar -jxf CocoaPods.app-1.0.0.tar.bz2
 6.01 real 5.04 user 0.74 sys
$ open CocoaPods.app

Cool. Done.

Ace. Now open the Podfile located in the project directory and click the ‘Install’ button. (Or if you’ve let the app install the CLI tool, you can use that instead.)

$ time pod install
Setting up CocoaPods master repo
[…]
Pod installation complete! There are 10 dependencies from the Podfile and 16 total pods installed.
 383.99 real 347.29 user 67.92 sys

Ok. Done. Now what?

That’s it. As the docs state, you open the Xcode workspace and just build. You need not perform any settings changes or add frameworks to link phases at all.

Duration: 6:42.31 minutes.