How do you onboard newbies onto an existing codebase?

For several years now the number of open source projects is constantly increasing and the number of developers is increasing every year. This raises the question of the newbies onboarding on these projects. That's why it's easy to find articles on the internet explaining how to start participating in an existing codebase. But today we are going to reverse the question. As a team, how can we make new contributors understand and master the codebase faster and better? Whether the project is small or big, closed source or open to the world, this is an essential and yet often forgotten point of the code quality. This topic is becoming more important with the current trend towards remote work.

Documentation, of course

We are going to start with an obvious, yet indispensable topic: the documentation. Of course, we are talking about the developer documentation and not the user documentation. In projects with many contributors on Github like React, Tensorflow or Angular, we regularly find two files for newcomers: a code of conduct and the contributing file.

The first one explains the rules on how to be part of the team/community by defining standards of an environment that respects everyone. This is where we exclude unprofessional behaviours and demand respect for everyone and everyone’s work. Its rules, although self-evident, are important to write down in large scale projects. For smaller projects, and especially for private ones, it could be a global note for the whole company/team.

The second file, on the other hand, is a lot more oriented towards the technical aspect of contributing to the project. It contains the processes and rules that drive the work on the repository. It’s the source of truth for all developers, not only new ones. Whenever there is a question about merge strategy, pull request requirements or commit message for example, the contributing file must contain the answer. Everything that is decided on development strategy should be explained in plain sight. You can never be precise enough. It's better to be too detailed than leaving blurred lines that can be misinterpreted by outsiders. 

Now that new developers know how to participate, they need to understand the project and for that they should read the technical documentation. This is, for many programmers, the most difficult manual to write but it’s one of the most important. This is essential in order to discover the technical complexity of the project, but it is also a good companion during the early stages to guide new people on the codebase understanding.

Once you have all of that, don’t forget to update it. In addition to the project evolution, we cannot write down all the necessary information alone. So the documentation must be updated with the project itself. Having documentation is good, updated documentation is even better!

Your homemade TDD

Now that your new member has read and learned alone, it’s time to share. Lots of teams jump this step and go straight to programming, but at Ponicode, we don't do things like everybody else. We love doing TDD! No, I'm not talking about Test Driven Development but Technical Deep Dive. The idea is for a senior developer to spend time with a junior one to explain the project architecture and answer questions. This may seem obvious to you, it is often the simplest things that work best. We simply choose to enforce this workshop for everyone. This helps us to answer questions quickly during onboarding and not leave developers in the dark for days.

Like we said before, the next phase is programming. But once again, it’s not about dropping your new friend alone on the darkest part of the codebase. So we choose to set up a peer programming workshop. I think you get the principle: 2 developers or more work together on the same issue. This is perfect to continue the previous deep dive, pass work habits, best practices and this goes both ways. It’s not only about training a developer, above all it’s about sharing knowledge and ideas. A fresh eye can bring fresh ideas and highlight some bugs or improvements to make. The more time that passes, the less peer programming is really required but we think it’s a best practice to enforce even after onboarding to ensure team spirit and knowledge spreading.

Issue flag not pirate flag

It’s often difficult to find the ideal first subjects when a new member arrives. This is contradictory because projects are always full of small bugs or non-urgent functionalities that can be done but we don’t think about it at the moment. This is why many projects have a "new member" label on their Github issues to indicate that it is a good place to start. It doesn't matter if you are on Trello, Jira or even Excel, the idea is to maintain a list of topics that can be given to newcomers. To be really useful, this list should not simply contain the name of the feature/bug. Ideally you should have as much detail as possible such as:

  • the desired behaviour or the method to reproduce if it's a bug
  • the name of the reporter to ask questions to
  • A screenshot if necessary
  • The function/filename where the code must be updated (if possible)
  • Any indication on the implementation (if possible)

Basically everything that can guide the developer.

You need to test - Unit test

I'm not going to insult you by explaining all the benefits of tests and specifically unit tests. We’re going to talk about the advantage for newcomers. I think it’s very reassuring to know that some tests will fail if you break something. It’s literally the purpose of unit testing; to detect regression. But once again, simple ideas are often the best ones. A real plus is to automate unit tests on a continuous integration pipeline so you won’t forget to run it. Tests are also good code samples to understand function or method usage.


Last but not least, code reviewing. In our personal opinion, review is the most important part of the development process. In addition to reading, testing and asking updates on the pull request, this commitment should be an amazing sharing zone for the team. Indeed, pull request reviews should be the best place to ask questions about how a piece of code works or any implementation details. We think it's not worth seeing the comment section as a punishment but rather a real opportunity to conduct peer programming and knowledge sharing. Personally, I've never learned more about a project and the best practices than by reading and asking questions about other people's code. 

There would still be a lot to say about onboarding on a complex code base like code formatting, folders structure, comment policy or naming convention but here we wanted to address the most important ones for us. Our new member training program is constantly improving and we love sharing it. So don’t hesitate to send an email to to say hi !

The Ponicode Team 🦄 🌈 🚀

Start automating your unit tests today

Green blobred blob