Mechanics of contributing

One key difference is the turnaround time. With every first time contribution you are coming to a new (host) team. As a result, you’ll need to get to know their code base, technologies used, and also their preferred development environment (think test framework, build system). Even in cases where this type of tooling is standardized, each team will have developed some individual peculiarities. In addition to the technical side, you may be faced with differences in communication (think code reviews). Even if you are coming back after a while, the teams' ways and members might have changed. Take your time as you would to catch up with a friend you haven’t seen in a while and whom you are visiting now.

Give yourself enough lead time. Start early enough, so that your work is available for you to leverage at the time you need it. It’s better to add more slack time initially - you’ll get a feeling about the turnaround times once you work with the host team. Often, you will notice a reduction in turnaround time per host team after making a few successful contributions to that host team. This effect can be observed with Open Source as well, you can read more about it here.

In your classic teams everyone had an idea of the expected lead times. Within an InnerSource context this might not be the case, either due to large time-zone differences (e.g. Seattle, USA with PDT vs Berlin, Germany with CEST) or you not being available full-time as with your original team, even if they are in the same physical location as you are. Thus, to prevent frustration on both sides, impatience and other non-trust-building effects, you’ll need to explicitly do expectations management with regards to your expected reaction times. One approach is to just quickly react with a "I’ll look into it, I won’t get to it in the next few days though" to a Trusted Committer’s feedback if you know that you’ll only be able to come back to them in a few days. Ideally, you can provide them with a rough estimate when you will likely have time to take a look at their input. Doing so builds trust by reliability even over non-physical contact, longer distance or otherwise asynchronous media. Established trust will allow you to overcome uncertainty bumps in the collaborative road ahead of you.

InnerSource puts huge weight on written communication - in particular when it comes to project decisions. Does that imply that in-person communication is forbidden?

Clearly not: while written communication shines when it comes to archiving and searchability, in-person communication shines when it comes to communication bandwidth. Try to make time to meet with people behind the names. If possible, try to meet them over your favorite beverage or some food. When you’re able to hear people speak, when you know their idiosyncrasies, remote collaboration will become easier.

Do you have a large feature that you want to contribute? Excellent! Wouldn’t it be horrible if all your work would be wasted? That can happen when the host team is already building something very similar, is planning to deprecate the software, or does not see what you are proposing to be a fit for their project. This challenge is a frequent one, and many team relationships suffered from not agreeing in advance that a contribution is a good fit.

Make yourself and the host team happy (and possibly save some work) by getting agreement from the host team on the user/technical design of the contribution before working on the changes and submitting a pull request. You’ll have to understand how the host team would like you to reach out for this. It’s best to ask a Trusted Committer about how to best discuss your proposal.

It is time-and-again-proven wisdom from the Open Source arena that, if you get to select how to discuss your proposal, you should try to select a written way. Ideally, choose the way where artifacts are public, searchable and perma-linkable to enable referencing your proposal in later discussions on this future contribution or other contributions to come - by you or others.

This type of high-level, early upfront agreement will save time in rework or rejection of your pull request down the road.

Great, you’ve made yourself familiar with the host team’s approach, and they are looking forward to receive your pull request. Which gotchas are there waiting for you now?

First, you’ll be in less direct contact with them. Second, you aren’t expected to be as knowledgeable and proficient as you might be on the full-time projects that your team owns. How can you now deal with this the best?

Try to peruse their documentation, the conversation archives and code artifacts from the host team to unblock yourself. This is similar to the situation you and likely most people find yourself in when using one of the popular OSS projects.

Much like in Open Source projects, ask the host team if things are going nowhere even after trying to unblock yourself. The questions you ask and the answers you receive will help others coming after you solve the same issues. Make sure that your communication ends up in a searchable archive that is closely linked to the project itself. Should you see easy improvement opportunities to reach said goal if it is not reached yet, you could try to - very politely - suggest an improvement to your host team. Sometimes the status quo arises from pure happenstance and stays that way because no one had a different idea or cared enough. Suggestions for improvement might be welcome in such cases. It doesn’t do either side any good for you to spin forever on a problem that could be resolved in a few-minute conversation with someone more knowledgeable about the project. It’s OK to ask for help.

There’s one key difference though, bringing advantage to you and other people in the future: In almost all cases you should prefer the projects' official communication channels - this can be a mailing list, a chat room, an issue tracker or something similar, depending on the purpose of having a more synchronous or asynchronous way of interacting, or the varying needs for structure in the communication. All of those usually have in common that they are text-based, archived, searchable and come with stable links - this means your question and the answer will be written down, and the references you link in those answers will also be kept reachable. This way you can benefit from this passively documented knowledge in your search AND help future contributors have the same advantage. Such passive documentation could even serve to enrich 'official' documentation, should it happen to contain especially valuable gems - such as important definitions that got created ad-hoc.

As you work, if you find missing (or out-of-date) documentation, do a favor to the next Contributor and update it with what you’ve discovered. Project teams are often happy to receive additions, updates or corrections for their existing documentation - you’ve just found another opportunity to contribute! (Or just politely provide them with a feedback on your experience, and what would have helped you.)

We all have our preferences and opinions on code style, indentation, etc. The host team’s project has them as well. Try to adapt and match those preferences even if it’s not what you would normally do, and even if it is not specified in the projects' `CONTRIBUTING.md`. If you are unsure, you can always ask politely. Nevertheless, a guest contribution for a feature or a bug fix is not the time to introduce a new way of structuring or formatting project code.

The basic point here is to enable the Trusted Committer to validate the contribution without your presence and to ensure easy maintainability. Imagine you’ve built a feature or handling of an unsolvable quirk, or an important performance tweak, and your code is not entirely obvious (or might even look hacky / wrong at the first glance). If you have covered this with a test - and ideally have shed some words on the rationale behind it in a comment - a future editor will get reminded about the purpose of the code, and the test(s) will ensure that the value your code realizes will be kept, even in the new implementations. To achieve this, do the following:

You want to ensure that your pull request includes any documentation updates that are relevant to your changes. Should the documentation live in a different place, make sure you add them there and link to them in your pull request.

To make the actual code review as easy as possible for the trusted committer or other persons reviewing it, try to follow these hints: