Your project is not ready for contributors

We all knew that kid growing up. I can still picture my friend Tommy’s basement. Tommy had all the latest toys. Electronics, miniature cars, sports equipment, collectibles, he even had the toys that I was told were ‘too expensive… I’ll talk to your father’ — Mom

Tommy’s home was a consumer wonderland. It was like a fine tapestry composed of the latest goods. If I saw a commercial for it on Saturday morning, Tommy had it by Sunday afternoon. I thought his parents were the best. I couldn’t possibly imagine why mine were so cruel. Tommy truly had everything. There was only one problem:

Everything was broken!

The electronics needed batteries. The video tapes were lost under the couch. GI Joes were wearing the wrong uniforms. The nerf guns had cracks in their oxygen tanks. The super soakers had cracks in their water tanks. Every lego set had critical blue pieces replaced with yellow ones. The baseball gear was one mitt short for our small team. The soccer ball was deflated. The gameboy had a dead screen.

I am not kidding. There was a purgatory-like aspect to hanging out with this kid. My wildest material dreams were at my disposal. Despite my dreams, each item was one critical flaw short of usability.

Contributor Readiness

Over the next few months I would like to discuss my observations and lay out a framework for project contributor readiness. I propose that your project has no chance of growth. It has no chance of going anywhere. It has no chance, if you can’t make it easy for contributors to onboard, to stay, and to grow.

But wait? My project has X brilliant teammates. They work hard. That counts, right?

Not so fast!

• Did you ever ask them how bad their on-boarding experience was?
• What would happen if you had to work with less-experienced help?
• Have they contributed in any way to improving the on-boarding experience?

These questions are likely to bring you to the sad realization that:

• “It was not great, the person next to me got a lot of questions”: “Where is the database credentials file?” || “What version of node do I need?” || “Can I use a reliable debugger in this environment?”
• Smart, motivated, experienced people do just fine because it’s always like this. Junior developers may get bewildered and second-guess themselves.
• “No, too busy writing super important feature Y.”

My Proposal

Your project is not ready for contributors. You need a checklist. You need guidelines to make sure you’ve covered your bases. The contributors you have are talented, bright people from within your network. There is a very limited supply of these patient humans. You have probably already exhausted it.

There are five areas you need to refine. And you should have a standardized system in place so you can implement this more effectively every time you go through this process. Here are your five areas of focus:

1. Access
2. Environment
3. Data
4. Tools
5. Testing

Today’s topic is access. Access comprises the basic permissions that ensure your developers can actually do the things they are paid to do. The sensitivity and complexity of this process varies depending on the kind of business. It ranges from low-key startup security practices to government-level security.

Whatever your policy limitations, there is absolutely NO excuse for making your service access unclear, inconsistent, or complex for those getting started. Allow me to repeat, NO excuse for needless barriers to entry for the incredibly well-paid professionals on your project.

Redundancy in environment management is a big part of the equation for more sensitive security situations. Let’s say there is a project that has three stages of databases inaccessible to developers. How many databases do you need to provide, minimum? The answer is four. NO excuse for the complexity of developers working in the dark.

Given that I am expecting a developer-friendly level of redundancy, let’s just assume that all the systems and processes I mention to follow are available to developers.

Welcome Email

My preferred on boarding approach takes the form of a welcome email. This has the primary advantage of being easy to reference, easy to track, and understandable to contributors that have worked in all environments.

The welcome email should be a template. This is not to say that it cannot be personalized for the specific contributor. Regardless, 80% of the work should be done by the template. Manage the template however you prefer. Gmail canned responses are simple and easy enough for my taste:

This email is succinct. It also answers all the questions this teammate is likely to have on the first day.

Version Control

The first order of business is version control. I am primarily familiar with Github and Bitbucket. They typically send out invites to any contributor that has been invited to the repository. It’s possible you can customize this invite, but I have not tried. I usually let developers know they should have received an invite in the welcome email.

This is an easy one. If you cannot get this right, your project is doomed. Just give them access, simple.

As an added bonus, I recommend a contributor guidelines video. This is a video that demonstrates how you prefer to manage pull requests. You can extend it to discuss the format of pull requests or commit messages. If you are really going for informative, I would recommend including a bit on why your team prefers rebasing vs. merging or vice versa. If you prefer for contributors to squash commits, include that as well. This is the most repeatable information imaginable. There is no reason not to create a screencast, like this one:

Sample contributor guidelines

Issue Tracking

Also an easy one. I argue that access to the issue tracking system is as important as version control. And sure, developers cannot write or contribute any code with the issue tracking system alone. Instead, issue tracking deserves a front-seat because it should be taken seriously by all your teammates. If you deny issue tracking this importance, you are hinting that it should be ignored.

Your project is similarly doomed if you do not think that issue tracking is important. There are smaller initiatives that can manage with a whiteboard format (and sometimes it’s better). Format does not bother me, just make sure you have a way to keep people accountable.

As an added bonus, I recommend an issue tracking guidelines video. Systems like Trello are very ‘choose your own adventure’ regarding organization. It’s easy for teammates not to understand the system and ignore it altogether. Give your developers a demonstration of how bugs should be written. Give your developers a demonstration of how features should be split. Here is a super quick, simple example:

Sample project management guidelines

File Stores & Databases

Some people rightfully have reservations about putting these credentials in an email. For my part, I try to make sure my test databases are not filled with real, secure data. The same goes for S3 or whatever kind of servers you use to store your files. Because this is an article about process, and not about tools, take my suggestions as an approach. Use whatever system you prefer.

For my part, I would be happy to refer my team to a shared Google Drive folder with the necessary credentials. There are good reasons to give developers access to beta and production systems, but certainly not within an email. I would give out those credentials on an as-needed basis.

Make sure it’s plug and play. Do not give your developers loads of text files with different credentials. Sometimes a .env file in the root directory of the project is great. If you need to add variables to their path, create a script. You’ll reap benefits over the years. Can’t create a script? Give detailed instructions. PLEASE, do not leave your developers out in the cold for access to systems they need.

Some more secure systems have special database clients that are only accessible through the network. Make the process of getting to these clients available to your team. Complicated process? You guessed it, make a video.

Test Accounts

This could easily be included in the environment section (next month). Given that it’s about access, I decided I would include it here.

Your developers need to test your application. They need test accounts. They also need test accounts that expose them to different roles or states in the application. Have an application that interacts differently with different states of the system? Make sure every mode is included in the list of test accounts.

In the vast majority of cases, it makes a lot of sense to have the list of test accounts in the project’s README.md file. I have yet to learn of a situation where a dev test account was not appropriate for the README. One case where there may be better options is when your dev accounts are not managed by developers or QA. In the case they are managed by business or someone else, a shared Google Sheet may do the job. Since this is not about tools, just make sure it’s three things:

1. Immediately available
2. Updated as necessary
3. Thorough (all roles, all application modes, etc.)

In the case that your app has entirely customized behavior on a per-user basis, just cover a wide enough range of cases that no major features or missing. Ultimately, this is a chance for developers to quickly move on to new features and test scenarios before they hand them over to QA or customers.

That does it for my take on managing Access for your contributors. This series has four parts remaining, so stay tuned if you’re reading this at the time of publication. Appreciate your comments and feedback.