Run Your Project Like It's An OpenSource Project

October 2015 marked my 7th anniversary with EclipseSource. For s_even__years I’ve been working remotely for an amazing company!_ For those of you who don’t know me, I live and work in Victoria British Columbia (Canada), an 18 hour trip – across 9 time zones – to the EclipseSource headquarters in Karlsruhe (Germany), where most of my team works. Obviously I don’t make this commute very often.

But this is only one perspective. Here’s another way to look at who I work with.

As an Eclipse committer, I get the opportunity to work with excellent developers all around the world. But working remotely is not without its challenges.

Challenges

If a manager wants to know the truth about their projects state, they should follow the development team on twitter

Developing software is hard. Writing code is easy, but developing software is hard. One of the most challenging aspects of software development is not technical, it’s simple team communication. If you’ve solved the wrong problem, then your solution doesn’t matter. If you don’t know where to turn to for help, then you’re wasting your time. If your team is stuck, solving the wrong problems and wasting time, then you’re failing as a manager. These issues are magnified when working remotely since you cannot see your teammates physically banging their heads on their desks; and even if they do know where to turn for help, they may still be waiting 12 hours for a response.

What would OpenSource do?

Whenever I see a challenging software development scenario I always ask: what would OpenSource do? If a small team spread across a few offices is struggling, how does a large OpenSource project, spread across the world manage to continually ship quality code on-time and on-budget?

There are three guiding principles employed in most open source projects. Awareness, Autonomy & Automation.  These three simple principles enable large teams, spread across several time zones with vastly different cultural backgrounds, to ship software with ease. All development teams should employ these guidelines.

Awareness

History is not recorded for today, it’s recorded for tomorrow

In an OpenSource project, all communication is open & visible. Emails are not sent privately between members. The same should be true about any software projects. The whiteboard in the office might seem like a great place to track process, but keep in mind that not everyone can see the whiteboard. Use communication channels that everyone can subscribe to, and when all else fails remember, the commit history is the #1 Channel.

I start each day by reading the commit history to see what changed while I was sleeping. Consider the history described above. What work was completed? Is the billing system done? What about the credit card processing? Now consider the following history that describes the exact same work.

Obviously the second version is much easier to read. It should be clear that both the client side credit card processing and customer billing were added on March 6th. All the intermediate commits are gone and at all times the system is in a ship_able_ state. In short, each commit is perfect. Furthermore, a good source control system will link lines of code with the corresponding commit message, allowing you to see exactly why a line of code was added.

Use the commit history to tell the story of how your software was developed, and if you tell a good story you will thank yourself. Remember: The most daft developer you will ever meet is you, 6 months from now; and the worst developer you will ever meet is you, 6 months ago. Record history for yourself.

Commit Messages

If you spend hours, days or weeks implementing a few feature, take 10 minutes to explain it

When you commit code, make sure you are answering the following questions: Who, Where, When, How, What & Why. Most source control systems will help you with many of these:

• Who, Where, When: Handled for you by most source control systems
• How: The code itself should describe this
• What: A short description of the change Sometimes it’s hard to see the forest through the trees
• Why: Most Important! Why was this change made? Why was this implementation chosen?

Autonomy

Code talks, words walk

All developers should earn their stripes. Nobody, not even the newly hired Chief Senior Engineering of Everything, should be given write access to the source control system on the first day. Everyone on the team must earn access by learning the system, traps, pits, design and more. All developers should use the system they are developing to help influence the design.

While nobody should be given access to the system until the’ve earned it, all developers – even the 1st year co-op student – should make a change to the system on their first day and see the results of their hard work. Of course you’re asking how do you make a change to a system without access? The answer will become clear as we explore how OpenSource projects are run.

Automation

Continually ship, continually deploy

A ship-shipping ship, shipping shipping-ships

Each change to the system, each commit to the repository, each line of code, should result in a useable system. At no time should an engineer need to roll back a change, or just fix this last test case in order to deploy a working build. All changes should be tested fully before they are committed. Of course this means that all developers must be able to run the complete build, including all the test cases, on their local machine.

Projects should require no more than 2 steps to build. 1) Checkout code; 2) Build. If your system requires more work than that, then you are doing something wrong. If you require a complex environment with database tables and web-servers, consider shipping a Docker file with your build to automate this.

The automated build should do more than just build the software, it should validate the change with zero effort on the part of the development team. In particular, the build should:

1. Compile the source code
2. Link the artifacts
3. Run the automated test suite
4. Automatically check code conventions and formatting rules
5. Run static analysis and other tools to ensure that the code structure is correct

All developers should have access to this build on their local machine, and the same automated build should run on your continuous integration servers.

How does OpenSource do this?

After Monday and Tuesday even the calendar says W T F

Many of these suggestions may seem like crazy talk. After all, we just suggested that you must:

• Contribute to the system on day-one without access
• Ensure each commit is perfect
• Validate each change with zero effort
• Ensure the commit history provides an easy to read story of how the system was developed

The secret weapon that allows OpenSource projects to do this, across timezones, with very little direct communication, is a solid Code Review System with automated validation.

When I talk about this with other senior engineers I often hear things like: we sometimes perform code reviews so senior engineers can review the work of the junior developers; and this sentiment makes me cringe.

• Code reviews are for everyone on the team
• New team members should review code to better understand the system
• Senior engineers should review code to share wisdom
• A smart ignoramus should be able to review anyone’s code and give constructive feedback

A good code review system, like Gerrit, sits between all the developers and the master repository. Everyone on the team pushes their changes to Gerrit where an automated validation job is started. This checks that the code compiles, conforms to conventions, passes the regression tests, and so on. If anything fails, the developer can fix their commit and push it again. Only once it passes the automated validation, will another engineer on the team take a look.

A change may go back and forth several times before it’s finally accepted. The code review system gives all developers on the team a chance to discuss the proposed change, and even collaborate on improving it. And when a change is finally approved, a developer with commit access can press the submit button, merging the change into the master repository.

Conclusion

Many OpenSource projects allow anybody to commit code to their code review systems. This means that anybody can clone a repository and propose a change. Each change can be validated without any effort from the team, and only once a commit is ready to be reviewed, does a developer need to expend mental energy looking at it. With a good code review system, an automated build, autonomous teams, and solid team awareness, you can ship quality code on-time and on-budget – without requiring all engineers relocated to the same city.