How to get started contributing to open source projects

Submitting code to an open source project can be a very scary feeling. When I submitted my first pull request I was scared. Scared that I’m doing something wrong. Scared that my patch wasn’t useful. Scared that other developers would make fun of me. 

I slowly worked my way up, from submitting smaller contributions to random open source projects, to then publishing my first open source library TSMessages, to finally building and releasing fastlane, an open source project that is now being used by tens of thousands of companies.
I want to encourage more people to get started contributing to open source projects, this blog post will show you how important open source software is in today's world, and how it can help you grow as an engineer.

Why developers and companies use open source software

👴 Project stays alive much longer

How often did you use a proprietary software solution, only to discover that the service is discontinued a few months after you’re fully ramped up?
Open source projects can be more robust in regards of maintenance, because there isn’t a single company that can decide to stop working on the project. Instead you have a group of maintainers that invest time and resources into a given software. Even if nobody has access to the code repository, developers can fork the project, and push it forward. This is something that I’ve done myself multiple times for dependencies we have in fastlane.

🔧 Independence: you can fix problems yourself

What happens if you use a commercial software and you run into a blocking issue with it? You’ll have to reach out to the support team, and hope they take your problem seriously and provide a fix for you. If the product was shut down, you’ll probably have no chance of getting any help at all.
With open source projects you are in full control over the software you run: You can dive into the source code, make changes and run those changes in your code base directly, without the original author’s approval. Even if a project is not being maintained any more, you can still not only use the open source software, but also fix issues and extend its feature sets.

🤝 Trust

What closed source binaries do you include in your mobile app? Each of them adds a risk for your app and your users, as it adds multiple attack surfaces. You cannot tell what the binary does, it could be malicious, it could collect data you don’t want to track, it could call home without you knowing, it might have bugs causing other areas of the app to be slowed down or even crash, a man-in-the-middle attack might modify the binary while you download it, or the download server gets hacked as it happened with XcodeGhost just last year. A closed source binary as part of your build phase might even go as far as uploading your app’s source code, secret keys and other data from your local machine. Some of these problems also apply to open source projects, however you do have more control over them. You can fork the project, audit the code, and then periodically merge it with the upstream repository after auditing the changes.
There are multiple approaches to fix man-in-the-middle attacks and future XcodeGhosts, like checking the code signing of the app and comparing the hashes, however you’ll never be able to tell what the binary does under the hood.

📖 Knowledge sharing

Open source code enables every person on the planet with access to a computer and internet to read your code and learn from it. This is extremely powerful and isn’t done in a lot of areas. For example when studying physics, you’ll soon notice how many papers and critical information are hidden behind paywalls or kept secret by the author.
Artsy is a great example: their apps are open source, so when someone asks one of the engineers how they do X, they can just link to the source code.

🛠 Open source build tools

Since I’m working on developer tooling most of the time, I’m thinking a lot about how essential they are for a team to be productive. If they don’t work, you can’t ship to your users. Being in control of your most important infrastructure pieces is crucial to making sure you’re not dependent on third parties when :poo: hits the fan.
No matter if you work on mobile apps or something else, very often there are services that promise to take all the heavy lifting for you by providing a proprietary, hosted software solution. This is great if you are starting out, however, by relying on this kind of solution you accumulate technical debt that you will have to fix in the future.
With your business critical infrastructure pieces (which includes build and deploy tools) you’ll want to have the knowledge of how they work, and ideally the opportunity to fix problems and customize the setup to fit your needs. If something doesn’t work you can dive into the code base, analyze the error, and fix the problem. This might not be as relevant for indie developers, but for bigger companies with dozens or hundred of engineers depending on the build and release process, it is important to be able to fix systems as soon as they break.

Why contribute to open source projects?

Using open source software is awesome, but why would you care about working on one? 

📈 Scale of impact

It’s hard to imagine the impact you can have on developers all around the world when working on open source projects. 

You can have this kind of impact, either by working on an existing open source project, or also by open sourcing some code you wrote. Who knows, it might be the next big thing :)

🤔 How did I get started with open source?

The first time I got into open source, is actually when I open sourced my first project called “TSMessages”. When I was showing my little app to Matthias at CocoaHeads in Vienna, he asked me if I can open source the custom notification bars I built. I didn’t know a lot about open source back then, but Matthias was kind enough to help me with the process.
At the time of release TSMessages had 2 classes and less than 400 lines of code. Within the next months more and more people started using it, resulting in a total of over a million downloads. Currently the project is actively being used by 13,000 apps.
Without me having to put in extra work, I didn’t only use TSMessages for all my personal apps, but helped 13,000 other companies to show better notifications in their apps.

Impact with fastlane

fastlane started as my Bachelor project, where I put the code on GitHub after completing the first tool deliver. One tool led to another, resulting in the fastlane umbrella tool, containing 17 standalone tools, 170 built-in actions, and 180 third party plugins. Today fastlane has saved over 9,000,000 developer hours and is used by tens of thousands of companies around the world.
I never expected the project to grow this big. It started by only solving the problems I had as an iOS developer. No matter how small you think a script or tool is, it will probably help other developers out there who face the same challenges. Only 9 months after releasing the first version, fastlane joined Twitter, and I helped build a team around fastlane. Today, fastlane is a 6 person team based in San Francisco and Boston and is moving faster than ever.

👩‍💻 Career & Jobs

2 years ago, I didn’t know a single person working at one of the big tech companies. All the tech giants were a closed bubble for me coming from Europe, I couldn’t ask someone how it is to work there, I didn’t have anyone to refer me, I didn’t know how the companies are structured. After moving to San Francisco, working for Twitter, and now Google I have a much better sense of how things work. 
If you’re in the same position I was 2 years ago, and you’re thinking about working at Google, Facebook, or similar, one of the best ways to get in touch with someone there is to contribute to one of the company’s open source projects.

Larger companies that own open source projects, not always have the necessary resources to maintain all aspects of them. The organizations are happy about external maintainers, and depending on the team behind it, you might receive an email sooner or later :) 

📃 Resume

Listing open source contributions in your CV is powerful. It shows engagement in the developer community, and that you’re potentially familiar with established tooling and frameworks in your field. Depending on your contribution, it demonstrates that you can navigate around in an existing code base, identify an issue, debug and fix problems, or extend the project’s feature set. The majority of engineers use open source software for their projects, however only a small percentage also contribute. It’s definitely a great plus point for every resume.

👍 To sum up

  • Learn new technology
  • Improve a project you use
  • Pimp your resume
  • Collaborate with people you would otherwise never work with
  • Your code could end up being used by millions of users (literally)
  • Internet points: the maintainers might tweet about your contributions
  • Many projects attribute their contributors on their website, or changelog - this has the nice side effect of boosting your personal search engine visibility also, especially if your name is common

How to get started with open source

Hopefully I got you interested in contributing to open source software, so the next question is, how do you best get started?

📢 Subscribe to a repo you’re interested in

By subscribing to notifications of an open source repo, you’ll get a good sense of what the community is like, what problems the contributors are facing, and where you can jump in to help. After a few weeks of being active, you’ll get a good sense of what the community is working on and how you can help.

🤠 Don't be discouraged, try contributing, people will help you

It’s scary submitting your first pull request to a new project. Some projects might not be looking for new contributors, so it’s a good idea to subscribe to a project before starting to contribute, so you get a feel on what the community is like. 
With fastlane, we welcome all new contributors, mention every single one in the release notes by name, and after successfully getting multiple PRs merged and helping other people, we promote them to core contributors

🚌 Contribute to projects that are widely used, but have a low bus factor

There is a lot of open source software that’s being used by hundreds of thousands of projects, but only have a single maintainer. Often those projects are so foundational of everything in an ecosystem, that people forget it exists. This is your chance to go through the list of projects with the worst bus factor and jump in and help.

The "bus factor" is the minimum number of team members that have to suddenly disappear from a project before the project stalls due to lack of knowledgeable.
Source: Wikipedia

One example of where things went really wrong was the left-pad project, a tiny JavaScript library that was maintained by a single person, that broke thousands of projects.

👪 How to join the development team of open source projects

Becoming a core contributor of a project very much depends on the size of the project:

  • Hyper-scale open source projects (e.g. Swift, React Native): It’s going to be pretty difficult to stand out, as there are hundreds of active maintainers, and it’s hard to tell how actively the owners of the repo monitor the activity of contributors. Very often, those kinds of projects have mailing lists you can join.
  • Projects that are popular and the go-to solution in its field (e.g. devise, CocoaPods, fastlane): Those projects are a great opportunity to have extremely high impact on other developers, while still having a rather small core development team. 
  • Low bus factor projects (see bus factor list): It’s rather easy and informal to join the development team. It’s usually enough to ping the current maintainer and ask about the plans for the project, and how you can help.

For many developers, the most interesting category is the second one: You can have a lot of impact within a short amount of time, get visibility and you have the chance to join a welcoming community and it’s a great opportunity to learn from fellow developers.

🚀 Getting started

Sometimes it’s not so clear on how to get started, so here are some tips on what you can do in no specific order

  • Helping out with an open source project is usually rather informal, often it’s enough to submit a smaller pull request
  • Look at some older issues and pull requests, and see if you can help get them resolved
  • See if there is a Slack group, Gitter or email group you can join to see what the core team talks about
  • Read through the documentation and guides to see if there are parts that aren’t clear and need updating
  • Most projects at this size will have a CONTRIBUTING.md file that explains how to get started with contributing code, and helping users
  • There might be additional documentation on how the project is structured and where to get started
  • Many projects will have outdated documentation, it’s a great chance for you to get some “internet points” by improving those
  • Adding more tests to existing projects gives you great visibility on how the project works, while at the same time making the maintainers very happy. Unit tests are often self-contained, making it easy for you to add them.
  • Subscribe to the repo to see how the community members interact with each other, and get a sense of what problems the project is facing
  • Some projects have a “you-can-do-this”, “help-wanted” or “beginner-friendly” GitHub labels, that are usually simpler fixes with some instructions provided by the maintainers.
  • There might be monthly video calls to align the whole development team
  • Onboard the project from a new user’s perspective, and see if there are any rough edges you could improve
  • The core team might be active on social networks like Twitter, make use of them
  • If you have an idea on how you can improve the project, submit an issue first to get feedback from the core team before spending time on building it. This is especially important if it’s a new feature that will need to be maintained in the future. Don’t forget to look if an issue for this specific idea was already created.

The most important piece is to get out there and submit pull requests, the rest will happen automatically.

🎁 Wrapping up

Developers and companies become more and more aware of how important it is for their dependencies to be in open source, not only to see what’s happening under the hood, but also to be able to fix problems themselves or even run their own fork if needed. This is especially relevant for build and deployment tools, but also third party SDKs you ship with your app. 
It has never been easier to get started contributing to open source, all it takes is a computer with internet access. As an engineer, it’s a great move for your career to get involved in open source communities: You have great impact outside of your usual work scope and have the chance to work with people you’d never otherwise work with!

If you’re still unsure, and need help getting started with your first contribution, please send me a private message on Twitter (@KrauseFx), I’m more than happy to help wherever I can 👍


Shoutout to my friends who helped me with this blog post: @orta, @hemal, @schukin, @_caro_n@acrooow, @sebmasterkde and @domysee

Analyzing your public GitHub contributions using Google Big Query

Do you like those GitHub graphs, but want to know even more about your open source behavior? GitHub has you covered with githubarchive.org. GitHubArchive offers dumps of all GitHub events of all users and open source projects. New ones are generated every single day, and are instantly accessible. They are very easy to use together with Google Big Query.

If you have a Google Cloud account & project, click this link to give it a try. Use the Run Query button and wait for about 30 seconds, and you'll get a list of people that comment on any of the fastlane repos most often in the year of 2017 (see screenshot below):

To run this query for your own GitHub organization, just replace the "fastlane/%" with your own GitHub org. You can also easily extend the query to show more columns (see the list of available events).

Running queries on your own profile

I was wondering of how my GitHub behavior changed over the last few years, now that fastlane is actively being used by tens of thousands of companies, it’s harder to keep the innovation you had in the beginning.

The last 3 years I published a total of

  • 16,000 comments
  • 5,550 Pull Requests
  • 907 releases

across a high number of different open source projects, mostly fastlaneTSMessagesdanger and lots of other projects.

Below you can see the last 5 years of open source code contributions:

Over the last 3 years, on average I did the following every single week

  • Post 77 comments on GitHub Issues
  • Submit 28 Pull Requests (the first year of fastlane, I didn't submit PRs on my own repos)
  • Posted 16 comments on GitHub Pull Requests
  • Published 5 fastlane releases

Wrapping up

You can extend those queries to show you more information that’s relevant to you. I initially wanted to use this to see which of our contributors are the most active, and make sure we promote them to be Core Contributors.

There has been quite some discussion around the GitHub graph (e.g. isaacs/github#627), as many engineers took it far too seriously and tried to have a long streak without any interruptions. GitHub reacted to the feedback and removed the streak count from all profiles, and added an option to show private contributions on the graphs.

Special thanks to @sebmasterkde for coming up with the initial queries.

Note: The data shown above is from May, as that’s when I wrote this blog post, but was kind of distracted with more important things (life and such) and finally found the time to publish this post.

What is the value of iOS code signing?

All those hours you spend on getting code signing to work properly on your machine, on your CI and on your co-workers Mac… your app and the App Store would be just a safe and secure without it.

Is code signing really a problem for developers?

Yes! On the fastlane repo alone, over 1,700 GitHub Issues are related to code signing. That is over 30% of all incoming requests. On Stackoverflow you can find over 3,000 questions around iOS code signing, even though it’s not related to actual code.

Why do we have to codesign iOS apps?

Code signing is one of the most crucial security components of the iOS ecosystem:

  • Code signing allows Apple to control what software can be installed on iOS devices. 
  • Code signing ensures your app doesn’t get modified by a third party on the way from your Mac to the end-users iPhone.
  • You sign your app with your signature, it ensures that the app is from you.

What’s the problem with the current process?

Once someone has access to your Apple credentials, they can easily revoke all your certificate, create new ones, and update the provisioning profile to use theirs. 

  • When you submit your iOS app for review, the app gets resigned by Apple after being approved, so your code signature isn’t actually used when the end-user downloads your app.
  • When you create a new Certificate Signing Request you can select `Saved to disk`. This means, if someone has access to your Apple Developer Account, they can create as many new, valid certificates as they want, without having access to your email account.

For many iOS developers, the account credentials never leave their computer (e.g. if the use Xcode and fastlane), but there is also a handful of third party web services that ask for your Apple ID credentials, which are then stored on their servers. If the service isn't open source, there is no way for you to know how the credentials are stored and secured.

How to fix iOS code signing? (see what I did there?)

Don’t require developers to codesign, or make it completely automatic

Don’t require code signing locally on the developer’s machine at all. Tools like the iTunes Transporter already verify the checksums and validity of the uploaded binary. Just by doing this one thing, you never have to deal with code signing again. 

And assuming your Developer account doesn’t have 2-factor auth enabled, there would be no difference in the security across the whole process.

The alternative would be to do all the code signing completely automatic in the background via Xcode. That’s already the case (previously known as Fix Issue button), and it works great for some use-cases, however once your team reaches a certain scale, you’ll quickly run into its limits (see codesigning.guide).

Enforce 2-factor

Enforce 2-step verification for all Apple Developer accounts, offer a way for teams to easily add multiple phone numbers or email addresses. Access to production apps is important enough to enforce 2-step verification for all accounts.

Require 2 factor auth before resigning the app

Once your app is approved, the owner of the app should be asked to confirm that this version should be shipped. This can be done either via email or SMS verification, but not via the iTunes Connect Web UI directly, as otherwise people with access to the portal could confirm your app release. This could even be its own iTunes Connect role.

Entitlements

Right now Entitlements are set up on your local machine. This could either be moved onto the server side on iTunes Connect, or work automatically under the hood on your local machine

Local code signing is still required for Development builds

You’ll always need to sign your app to install it on your actual device, however this became a lot easier over the last two years, as more and more people can use their personal Apple ID to install their app on their real device. This is actually quite critical, as local code signing was abused by multiple app providers to enable people to install apps that are not approved by Apple (e.g. Flux for iOS)

Ad Hoc builds still require code signing

The above mentioned techniques won’t work for Ad Hoc builds, code signing should still be required as before.

Joining Google

In 2010 we visited the Google campus on our family trip to California. Ever since then I knew I wanted to work here at one point in my life. Today, 7 years later, I had my first day at Google in Mountain View, joining via the acquisition of Fabric. I'm so happy that I reached this goal, and I can't wait for what I'll learn over the next few months and years.

Scaling open source communities

Not too long ago I started an open source project called fastlane. Just a month after publishing, it had 1000+ stars on GitHub and was beginning to get used by lots of serious tech companies around the world. Soon I was the sole maintainer of a project getting 10+ PRs/day, and spending 8+hrs/day reviewing PRs and replying to questions on GitHub. This is the story of some of the challenges I faced when scaling the project to where it is today: a OSS project stewarded by Twitter and now Google, with over 12k commits, 13k stars, 500+ contributors, and one of the top 25 most active open source projects on GitHub (spoiler alert: I didn't do it alone).

Different stages of open source projects

Stage 1: Putting source code on GitHub

About 40% of all repositories on GitHub have 0 stars and don’t gain a lot of traction. Most of those repositories don’t have a single GitHub issue or Pull Request. For example, a very early version of fastlane snapshot was called rScreenshooter and has almost no engagement on GitHub.

Stage 2: Developers start using your software

It’s tough to know how many people use your code until you get your first Issue or PR. Receiving your first PR is an amazing feeling: Complete strangers care enough about your project that they gave it a try, and even dived into the code to work on an improvement, and send it back to you. However, simple PRs like a doc changes aren't signals that a developer is using your code. Only when a pull request changes the software’s behavior you know it’s being used, and it’s a great feeling. For fastlane this was the case a PR from foozmeat that improves the design of the app’s summary. Not only was that a great change, but also was it from someone at Panic.

Stage 3: Project is popular and the go-to solution in its field

Even more exciting times start when your project becomes the de-facto standard for the problem your software solves. In my experience you first realise it when someone on Twitter asks on how to solve a problem, and multiple people reply with a link to your GitHub project.

Examples:

  • Accessing SQLite in your iOS app: fmdb
  • Authentication for your Rails app: devise

Stage 4: Hyper-scale open source projects

If you finally are able to grow your user base wide enough, you might hit a new set of problems. Stage 4 is where the fun begins: you will get hundreds of notifications every day, there will be blog posts that attack your project and there will be commercial versions of your project, maybe even (partly) using your source code. Some of those projects slowly evolved to being in this category (e.g. rails), however more and more projects have a kick-start by being launched as a solid, finished open source project by one of the big companies like Facebook or GitHub.

Examples:

Scaling open source projects is hard

My time spent on GitHub compared to my text editor, with the growing popularity of fastlane, GitHub goes up more and more

Keeping the momentum

The bigger your project becomes, the harder it is to keep the innovation you had in the beginning of your project. Suddenly you have to consider hundreds of different use-cases, thousands of production setups and can’t just remove an option, or change a default value.

Handling support for open source projects

Once you pass a few thousand active users, you’ll notice that helping your users takes more time than actually working on your project. People submit all kinds of issues, most of them aren’t actually issues, but feature requests or questions.

Receiving feature requests

How you handle feature requests is up to you, there are various ways projects handle them:

  • Let people submit features as issues, and label them as feature request. This way other users can easily find them using the search, and upvote them
  • Have a separate page where users can submit and upvote feature requests
  • Don’t accept new features, and feature freeze your project

There are very interesting conversations when you close feature requests:  

Being in the public spotlight

As a maintainer you are under big pressure when dealing with those kinds of situations. Depending on the conversation, people can tweet screenshots, you might land on HackerNews or cause a shitstorm, causing hundreds of comments by random people on the internet. This distraction leads to many maintainers leaving feature requests open and unanswered, and not dealing with them altogether.

Due to the pressure of having 100% of your activities (both code and conversations) in public, lots of open source maintainers burn out. You can find hundreds of blog articles about software developers sharing their story (most recently “Dear JavaScript”).

Reviewing external PRs

As a maintainer you often have the responsibility to decide what you merge into your project’s code base, and what to reject. Very often these are very difficult decisions, which might hurt other people. When merging code changes that introduce new features or options, the maintainers have to consider the long-term effect of this change:

  • The feature has to be supported in future releases.
  • The feature has to be tested with all future changes.
  • When the feature breaks, very often the project maintainer has to fix it, unless the original author is still available.
  • Many users aren’t aware of this, and sometimes people get offended on GitHub when you say “No” to a new flag or option.

In general, reviewing and testing a pull request, takes almost as much time as writing the code for it. As a maintainer you have goals for your project, and work towards them. By receiving external pull requests without any prior discussion on a GitHub issue or mailing list, you have to pause what you currently worked on, to review and test this change without the same context or motivation that the PR author has.

It’s very hard to balance reaching your current goals, and investing time reviewing pull requests that don’t work towards them.

Maintainers stop being users of the project as it grows

This is an interesting phenomenon with many big open source project, including fastlane and CocoaPods: The project was started because the author needed the software for themselves. Suddenly they work on the open source project full-time, stopping the activity they’ve been doing before. With that they stop being a user of their own project. They are not in their own product’s target group any more.

The challenge is to still somehow use the product to feel the user’s pain points, and realize what to focus their time on. For example, fastlane is deployed using fastlane, therefore everyone working on fastlane also uses the product. If that’s not possible for your project, force yourself to onboard your own project from time to time, and go through the whole process.

Information imbalance with your users

Due to the nature of scaling software, there is a big information imbalance between the project maintainers and the users. For you as a maintainer, an issue is “just another issue” (one of hundreds), but for the user, this one issue is everything. This issue is 100% of the interaction with your product, and it’s something they will remember for a long time.

This first hit me when I attended my first WWDC in 2016, and iOS developers came up to me to talk about the GitHub issue they submitted a while back, assume I’d remember the whole conversation. This is not only the case for online interactions, but also when talking with users of your software.

For the maintainer it's an issue that has to be prioritized and it might not be the most important thing. For the user, it's everything and might keep them from using your product, and it’s the thing they are going to remember for a really long time.

The healthy way to scale your open source project

Improve your error messages

How you handle failures has a big impact on how easy it is for the user to resolve the issue. So many developer tools get that wrong (Thoughts on iOS build tools) and make it incredibly hard for people to use their software.

Before changing fastlane to highlight the actual error message and still showing the stack trace by default

After the change: fastlane now color-highlights the actual error message, and hides the stack trace by default, unless it's a real crash

The left screenshot shows an early version of fastlane, compared to how fastlane shows error messages today. Not only how you present the error message, but its content is really important: Make sure the message explains the error well enough and ideally even include instructions on how to fix it.

In fastlane we even link to StackOverflow replies and make sure to include all necessary information to debug an issue. In this example we show the certificate ID and team name.

Make it easy to find existing issues

When you receive a cryptic error message, what’s the first thing you do? Usually you search on the GitHub repo page, or google for the message. You as a project maintainer should make it easy as possible for the user to do so. That’s why @orta started gh_inspector, a Ruby gem to show related GitHub issues right in the user’s terminal. Whenever fastlane runs into an unexpected situation, it will not only show similar GitHub issues, but also print out the GitHub search URL. The long-term plan is to also support StackOverflow questions (see #13)

Whenever fastlane runs into an unexpected error it automatically shows similar issues on GitHub

Use of bots

I’m not a big fan of bots and automated messages, however as soon as you reach a certain scale you need to have some automated systems to reduce the support load.

Ensuring all required information is available

Providing all information when submitting a bug report is hard, even as a software engineer. GitHub recently introduced ISSUE_TEMPLATE.MD, that auto-fills the “New Issue” form with instructions on how to file an issue. However most people ignore the instructions.

Using the fastlane-bot we ensure all required information is available, and if not, tell the user how to provide them.

With that, fastlane also supports the  fastlane env command that prints out all relevant information:

The fastlane env collects all relevant system information, like your Ruby environment, OpenSSL version and used fastlane plugins, ready to be posted on GitHub.

Helping users is so much easier if you have all the information right there, including all configuration files, other dependencies and version numbers.

Answers based on keywords

If you receive similar issues very often, you should step back and work on fixing the underlying issue or making usage more clear. If 10 users submit a specific kind of issue, hundreds of other users felt the same way but didn’t take the time to submit an issue.

In the case of fastlane, many issues are related to code signing (yeah), however there is no ultimate solution to fix all issues as of now (codesigning.guide is the easiest one so far). We wrote an extensive guide on how to setup code signing and how to troubleshoot problems. As with most things, users don’t like reading manuals, unless you link them to the right spot, which is exactly what the fastlane-bot does in that case.

Many times just linking people to the right docs already helps

Stale issues

The key to handle support for large-scale open source projects is to keep issues moving. Try to avoid having issues stall. If you’re an iOS developer you know how frustrating it can be to submit radars. You might hear back 2 years later, and are told to try again with the latest version of iOS. Chances are high you have no way to reproduce the issue again for multiple reasons:

  • The user tried your software, submitted the issue, and went with a different solution in the meantime
  • The user already found a workaround, and doesn’t care about spending more time on this issue
  • Many engineers switch companies and projects frequently

Having a bot can ensure that issues are still relevant and reproducible. The fastlane-bot automatically asks if an issue is still relevant with the most recent fastlane release after just 2 months.

If no participant of the issue replies to the bot within a month, the issue gets auto-closed, with a note that a new issue can be submitted to continue the discussion.

About a month after closing the issue, the bot locks the conversation to repository admins only.

Locking resolved and inactive issues

Locking conversations of resolved, inactive issues is a great way to avoid re-surfacing GitHub issues from old releases. In the case of fastlane the following happened a lot in the past:

  • Users would comment on issues that are not related to their problem, however sound similar
  • Users would comment on issues with a lot of subscribers from a long time ago, triggering unwanted email notifications for people who already found a solution
  • The fastlane-bot doesn’t ensure if all required information is provided for single comments, but only for new issues
  • Users would add “me too” commented without providing any details of the current problem they’re having

By telling users to submit a new issue, you properly go through the complete lifecycle of an issue:

  • User submits issue
  • fastlane-bot ensures all required information was provided
  • Actual discussion around the issue
  • Issue gets resolved or auto-closed due to inactivity

 

Responding to pull requests

The sections above mostly covered issues, but a very essential part is also responding to pull request. You have certain rules for your projects, like automated tests, code style and architecture. Many of those things are already checked by regular CI systems, and the build for the PR fails if the requirements aren’t met.

However tests don’t ensure the way how changes are introduced (= the delta). That’s why @orta and I set out to build danger, a tool that allows you to define rules for code changes. Some examples:

  • Post test failures right on GitHub so that contributors don’t have to scroll through the CI output
  • Show a warning when certain files get modified
  • Require new tests when more than 20 lines were modified
  • And many more

PR and Run

This is something you can see in many open source projects, someone takes the time to submit a pull request, the build is failing but the author doesn’t update the PR. The reason for that is that there is no GitHub notification when their build fails, so you as a project maintainer now have to be the “bad person” to tell the developer to fix the tests. That’s time you spend on something, that should be completely automated. By using danger, you can have the CI post the test results right on GitHub triggering a GitHub email notification.

Steering the direction

It’s 🔑 to work into the same direction and have a shared vision. For open source project, most communication happens asynchronously instead of having meetings. Because of that, it’s a little harder to stay focused on going into the right direction.

Many bigger open source projects introduced a VISION.md (e.g. fastlane, danger) that describes the bigger-picture goal of a project and the overall philosophy.

This enables contributors of the project to say “No” to feature requests or PRs by referencing the written agreement in the repository. The beauty of this approach is also that everyone has the opportunity to submit PRs for the VISION.md document to propose changes in the policies.

Scaling contribution

As your project grows you need more people joining you on maintaining the project and pushing it forward. You want to increase the bus factor as your project grows, meaning more and more people know how the project works and can commit code. There are some great approaches out there, like the moya contributing guidelines by Ash Furrow. Ideally the project operates without any help from you.

Code of Conduct

With a growing community, you also need to ensure developers are in a safe environment. One action you should take very early in your project is to add a Code of Conduct (more information by Ash)

Onboarding instructions

Make it very easy for engineers interested in submitting code changes to set up their development environment. If you’re not a mono-repo yet (:trollface:), you might need a repo to quickly set up all the other repos, e.g. CocoaPod’s Rainforest, fastlane’s countdown (now deprecated)

Keeping your code base simple

This is something not many open source projects consider: the more complex the software architecture is, the more difficult it is to get started coding and less people are able to contribute. Instead of using the latest Ruby magic to save 4 lines of code, use the easiest to understand technique to solve a problem, making it easier for people to spot issues and contribute fixes and improvements.

Be welcoming and friendly

This has been top priority for me since starting fastlane. Always be as friendly as you can. Thank people for submitting issues and PRs. Ask people for help or clarification if needed.

Enabling your users to extend your project

When scaling your project you have to say “No” to many new features and ideas. Instead you need to focus on what your software is best at. However most software would be very limited if there was no way to extend it. Depending on the size of your community, there are two good way to achieve that.

Offer dynamic configuration files (ala DSL)

Many Ruby-based open source projects, including fastlane, CocoaPods and Bundler, offer a DSL that allows developers to implement a very dynamic configuration. Instead of having static values like it is the case in JSON or yml files, you can execute code in a Fastfile, Podfile and Gemfile. This is extremely useful to fetch or generate values on demand, like accessing an internal server for the latest app description.

Allow local extensions

This is how we started out with fastlane: when a user needed an integration for a third party or internal service that isn’t available yet, they can easily build and use a local action without having to touch the actual fastlane code base. Most of the times, the developers would store their local actions in their git repository.

Allow the community to extend and build on your project using plugins

Allowing local changes works great for a while, until users want to share their integrations with the rest of the community. Once that’s the case you need to provide an ecosystem (kind of like a marketplace) for developers to share their integrations.

While it’s not possible for all kinds of projects, building a plugin architecture enables your project to advance at a much faster pace. Your dependency graph will stay slimmer, you might receive less PRs adding new features and your core code base can stay smaller.

Of course you can build your own dependency resolving, however think twice before doing so. There might be a great dependency manager available you can use to implement your plugins.

At fastlane we use RubyGems and bundler to make it easy for people to distribute and use plugins. As a result there are already 120 third party plugins available within just a few months.

Wrapping up

Scaling open source projects is hard. Really hard. There are lots of challenges you’ll solve while scaling up. Ideally you’re not the person having to solve all problems that are caused by a growing project, but have core contributors helping you. Good open source projects stay alive for a really long time and you can have an enormous impact on developers and companies around the world with it. If you face challenges, don’t give up, ask the community for help. I personally have never worked on a project with such a great impact, and I feel extremely lucky to work on the right thing at the right time.
 

I described the above with the assumption that you would use GitHub for your open source projects. There are many alternatives out there, however to simplify the above text I decided to use GitHub with the terms “Issues” and “Pull Requests”.

Writing automated tests for your documentation

The 2 favourite topics of every engineer are usually unit tests and documentation. The last few weeks I've put some thoughts in how to combine those two things for the ultimate developer joy.

Why should I write tests for my documentation? 

  • You might forget to update parts of the documentation when you update your API or interface
  • Spelling mistakes happen in code samples
  • You want to make sure you don't introduce any regressions with a new release

With the launch of the new docs.fastlane.tools website, we took the time to set up a proper documentation system based on markdown files, converted to a static HTML page using MkDocs. By having full control over the generated HTML code, and going 100% open source on GitHub, you can do powerful things:

  • Fail the build when a page got removed from the index using danger (see Dangerfile)
  • Generate redirects when a page got moved (see generate_redirects.rb and available_redirects.rb)
  • Make sure the repo is in a valid states, and all documentation follows the convention
  • Write tests for your documentation

Tests for documentation, what does this even mean?

Just like with your actual code base, you want to be sure that your repository is in a valid state. The same applies for your documentation. Is your latest documentation up to date, and does it work as expected? Does it work with your latest release?

The first time I thought about running tests for documentation I thought only about the code samples. However you can write tests for a lot of more things. For example you want to ensure that all your assets are in the right sub-directory, that all referenced images and markdown files are available and follow your naming scheme.

Some examples of what you can do:

Validate file names

Ensure that all file names follow your convention - this is especially important if the file names are visible in the URL.

Ensure every page has a header

fastlane docs require a title on each page to be consistent.

Ensure all image assets are available and in the correct folder

Automatically verify all referenced image assets are available and stored in the right folder, find the source here.

Ensure spelling of certain words

Recently we switched from `fastlane` to _fastlane_ in markdown files, so we want to ensure all new docs use the new way of spelling.

Verify code samples

How many times have you copied a code sample to try it out, just to find out it doesn't work with the latest release? There are various reasons for this, and without tests there is almost no way to avoid this. The error can be as simple as a spelling mistake.

By having full control over your documentation, you can easily iterate over all your code samples, and make sure they work as expected.

For fastlane we found 28 errors just in the actions documentation, most commonly syntax errors or just simple spelling mistakes in parameter names.

For all the checks mentioned below, the source is on the fastlane docs repo.

Catch syntax errors in code samples

Nothing is more frustrating than copying a code sample and having to fix the syntax to make it work. Most users won't spend the time to look into how they can contribute to your docs to fix the error.

 

 

Catch unavailable actions or methods

For fastlane most code samples call certain actions or integrations. Using tests we ensure that this action is available and correctly spelled.

 

Verify action parameters

Most fastlane actions allow passing of named parameters. We now automatically verify that all parameters are available to use.

 

Verify parameter types

Every fastlane parameter has a type defined, which fastlane validates on run-time. It's easy to get a type wrong in the documentation, so we now validate those too.

 

 

When to run tests for your docs?

There are 2 points where you want to verify your docs are valid and up to date:

So whatever introduced a regression, the build will be failing and you can't merge the change into master.

Where to go next

These are just some things you can do with tests for your documentation, however I'm sure there are so many things you can automatically test and verify every time your code changes. Let me know if you have any ideas on what other crazy things you can do.

'trainer' - the simplest way to generate a JUnit report of your iOS tests

If you're running tests for your iOS code base on some kind of Continuous Integration, you usually have to generate a JUnit file to report the test results, including error information, to your CI system. Until now, the easiest solution was to use the amazing xcpretty, which parses the xcodebuild output and converts it to something more readable, additionally to generating the JUnit report.

Since there were some difficulties with the new Xcode 8, Peter Steinberger and me had the idea to parse the test results the same way Xcode server does it: using the Xcode plist logs

trainer is a simple standalone tool (that also contains a fastlane plugin), which does exactly that: Convert the plist files to JUnit reports.

By using trainer, the Twitter iOS code base now generates JUnit reports 10 times faster.

To start using trainer, just add the following to your Fastfile:

By combining trainer with danger, you can automatically show the failed tests right in your pull request, without having to open the actual output

For more information about when to use trainer, check out the full blog article on PSPDFKit.

Introducing fastlane device grid, one-click installation, 2FA, more APK management features, and emoji deployment

In May, we focused on making pull requests more powerful and introduced enhanced deployment options. For more details, check out the full blog post on fabric.io/blog.

 

fastlane device grid

Tired of locally compiling your app just to test and preview a change? From now on, you can test your app straight on GitHub from the pull request using device grid.

One-click installation via the Fabric Mac app

Want to install fastlane with one quick click? You can do it directly from the Fabric Mac app. 

Two-step verification

Looking to take advantage of two-step verification for stronger security? All fastlane tools now support two factor authentication. 

APK expansion file upload and APK promote to track capability

Last but not least, thanks to awesome contributions from the community, it’s easier than ever to upload APK expansion files and promote existing beta builds to production on Google Play. 

Read the full blog post on fabric.io/blog