As an independent consultant, I work for companies large and small. But I (lightly) engage in some open source work, from submitting bugs over creating pull requests to maintaining my own RedStar.Amounts library. The open source community has some best practices that are often missing in companies. Here are some that I recommend you try to introduce in your organization.
There is a minor disclaimer though: this is not true for all open source work. But most well-maintained open source projects adhere to these practices.
Add a Readme
Forget wiki’s, Word documents, Sharepoint or other archaic means of sharing documentation. When you create a library to share with other developers, add a readme in the repository. This has several benefits over other means of documentation.
First of all, it joins the lifecycle of the library. That means you can track changes to the documentation and see older versions.
It’s also the first thing other developers will see when the repository is hosted in a modern version control system (like GitHub, BitBucket, GitLab,
TFS Visual Studio Online Azure DevOps or whatever they’re calling it today). This means they don’t need to go look for any documentation or ask the original developer. It’s right there.
Equally important as adding a readme is what you put in it. The basics are:
- what it does, what it’s for
- how to install it
- how to use it (configuration, code,…)
Bonus points if you write down the API of the library.
If you want to reuse a piece of code, you are using some sort of packaging system, right? Right?
Alas, I’ve already encountered two or three companies that have set up complex custom systems of sharing branches across other repositories. The reasoning is often that they want to be able to debug the library. But the library can only run inside an application, so they need to pull in the sources of the library (at a specific point in time). This ends up in a gigantic mess over time.
A better option is to write automated tests and develop the package in isolation, version it, package it, and put it in some package management feed where other developers can pull it from.
Many companies have a custom versioning strategy, often because of legacy reasons. If possible, use what has become the standard in software development: semantic versioning.
There are lots of details to semantic versioning, but the easiest way of thinking about it is like this:
Whenever you change something, increase the number that corresponds with your change. If it’s a breaking change to the outside world, increase the major version number. A feature means increasing the minor number and a bugfix increases the patch number. In some languages, there’s room for a fourth number. Traditionally, this is the build number.
The power of semantic versioning is that it communicates very well to other developers. If I have version 2.8.4 of your library, I can easily see that an update to 3.1.0 could mean my application will behave differently. An update to 2.9.0 or 2.8.5 on the other hand shouldn’t be a problem.
This can lead to version numbers that go up quite fast, but it’s only a number. I once left a company with an application that was at version 30 something. That doesn’t mean it broke all clients 30 times. But I did introduce many changes that were considered breaking. Heck, if Chrome can do it, so can you. It’s just a number, albeit one with a high communicative value.
Giving Back To The Community
Raise your hand if you’ve worked at a company where someone took an open source project, forked it to make some changes, and never contributed back.
There could be good reasons to make a change so that the component can work in your company. But more often than not, maintenance of this fork stops after the initial changes. Which means: no more new features and no more bugfixes. All while the open source project is being maintained with absolutely no cost to your company!
Eventually, the original project will change so much, that it’s practically impossible to apply the company changes to the original. So it’s too hard to incorporate all the work of the open source community into the fork, and we leave it that way.
A better approach would have been to make the changes in a fork, and create a pull request, explaining what you did and why.
Participate In The Community
Another way of engaging the community is to communicate with the people in open source projects. If you’re stuck with something and think/know it’s caused by a certain library, submit an issue. Tweet the author. Send a mail.
I’ve often been helped faster than I would have found the solution myself. Time and money saved!
Develop Like You’re Doing It In Public
What this comes down to is to develop software in your company like you would be doing it for the world. That world is very small in your company, maybe only a handful of developers, but you still have an audience. There’s the current colleagues, but also others that might come after you’ve left.