What to know before you open source an internal project

Originally posted on opensource.com in June 2017.

Before your company makes a project open source, make sure you’re ready for all your new responsibilities to the community that forms around it.

Your company is going to release an internal project as open source. Congratulations! You know your code is ready, but are you ready for all your new responsibilities?

Once a project has been released as open source, your company is not only responsible for the project, but also for the community that will form around it. This often requires changes to the development/build/release workflow. This is not about the code per se; it’s about all the processes and infrastructure that surround the code that make the open source project successful.

Here’s what you need to know and expect before you release your open source project.

Identify your company’s goals

Before you go much further, take a moment to evaluate your company’s goals for releasing the project in the first place. The company will invest a lot of time and effort into preparing this for release—and a lot more in maintaining the project and the community that forms around it. While it’s possible that these efforts are altruistic, it’s more likely that the company expects something for its investment.

Make sure you’re aware of these goals before diving into the project and its community. Taking steps to ensure your company can meet them not only helps the company, it helps free and open source software (FOSS) overall. Companies that don’t know or don’t meet their goals with an open source project withdraw from FOSS participation entirely, and that helps no one.

Understand community expectations

While your company may still hold the keys to the kingdom and decide what contributions to merge and when to bundle a release, all development must be done in the open in communication and coordination with the community that forms around it.

In other words, the project must operate according to established community expectations for an open source project. These expectations include (but are not limited to):

• All development work—including bug fixes, new feature development, product roadmaps, and discussions and issue tracking about these things—occurs publicly and in coordination and cooperation with the community.
• All build processes related to the code (continuous integration/deployment, etc.) operate publicly and are accessible by and to the community.
• The company accepts contributions from the community, where “contributions” means not only code but also documentation, design, product roadmap guidance, governance, and other matters pertaining to the project. All contributions must be reviewed and considered promptly, and feedback must be provided publicly.

Know that community is key

Open sourcing a project creates a lot of work, though in practice it’s usually no more work than proprietary software development. Still, there can be considerable effort required to transition processes and culture to work efficiently and effectively in the open and support an open source community.

If it’s so much work, why do it?

As I mentioned earlier, businesses don’t usually release projects out of the goodness of their heart. They do it because they want to benefit from the community that hopefully will form around the project—but those benefits happen only if the company earns, builds, and maintains the community’s trust.

That trust happens by doing all work in the open and in communication and collaboration with the community. Any fully unilateral or private decisions the company makes will violate that trust and alienate the community. When a community is alienated, they leave (sometimes forking the code to start over elsewhere).

There is no way to benefit from a community that disappears. That leaves the company with a bunch of code that is open but no one uses or cares about, not to mention unable to meet the goals it set when it open sourced the project.

Launch your public issue tracker

Once a project is released, all bug reports—previous and new ones—must be available in the project’s public issue tracker. Here are some things you need to do:

• Move pre-existing bugs/tickets/issues to the project’s issue tracker.
  • Be aware that moving often requires a script.
  • Before you move anything, review all existing issues and close those that have no real hope of ever being fixed.
  • Make sure to remove any proprietary information from any pre-existing bugs/tickets/issues before moving them to the public tracker.
• Decide whether to move closed bugs/tickets/issues to the public tracker.
  • This is optional, but it can provide valuable context for future development.
  • Make sure to remove any proprietary information from any closed bugs/tickets/issues you plan to move before making them public.
• Create a new workflow so all bugs/tickets/issues will be routed efficiently to and through the public issue tracker.
  • Coordinate and train all company staff who report or interact with bugs/tickets/issues.
  • If you use a publicly available issue reporting tool (e.g., ZenDesk), the new workflow must ensure that issues reported there are efficiently transferred to the public issue tracker and the reporting parties (usually customers) still receive the service and information they have come to expect.

Be ready to open your product roadmap

Once a project is released as open source, its development roadmap and all related discussions become publicly available.

• All discussions and decisions about what goes onto the roadmap (and why) must now be held publicly and with the community’s input.
• Community feedback should be integrated into the roadmap.

Please note: While the roadmap and all discussions about it occur in the open and with input from the community, unless it has made other accommodations the company may still have the final word on what goes onto the roadmap, when, and why. This should be done in a manner that is respectful of the community the project now serves and supports.

If the public roadmap includes features that interact with or rely on proprietary features, everyone who interacts with the project must be careful not to leak proprietary information in discussions about the public roadmap.

Define the contributions workflow

Once a project is released as open source, all contributions to it must use one public-facing workflow, regardless whether the contribution is from the originating company or the community.

Here’s an example of a typical workflow:

• A contributor forks or clones the public repository to their own computer.
• The contributor creates a feature branch of the repository and develops their contribution on that branch. This work, as it’s being done on their own computer, is private.
• Once their contribution is ready, the contributor submits their contribution back to the public repository. (The process depends upon the version-control system in use and the preferences of the project.)
• The contribution is publicly reviewed by community members who are qualified to do so (typically known as core contributors). These people then choose to merge, defer, or close (decline) the contribution. If the contribution is merged, it may be to master/head or a different branch, but this depends on the project’s needs and workflow.

Each project must consider and decide upon its specific contribution needs and workflow and make these publicly available in the project’s CONTRIBUTING.md file.

Don’t forget about the build process

The build process is often overlooked when planning to open source an internal project. This is unfortunate, as the build process also happens in the open once the project is released.

Some things to make sure of when opening the build process:

• There is no proprietary or internal-only fork of the code.
  • If there is, it will betray the trust of the community, who will leave.
  • It will also greatly increase the work required to merge and maintain code.
• All build processes must work against publicly available code, either the master/head or a stable branch maintained for build (whatever makes the most sense for the project and product).
• All build artifacts should be made publicly available immediately upon build completion.
  • How they’re distributed after that (e.g., pushed to customers) is a business decision, but the build artifacts (including final binaries) are always publicly available.

Support open discussions of community governance and tooling

Once a project is released, all decisions that impact it or its community must be made in the open, including changes in governance, adjustments to tools such as version control or continuous integration, and changes or additions to communication routes.

This does not necessarily mean that every tiny decision must be sent to committee or requires full discussion from the entire community. Often it is enough to solicit suggestions and feedback from the community and consider them when making decisions.

All final decisions, the reasons behind them, and their expected outcomes must be publicly announced, available, and documented in whatever tracking system the project uses for such things (usually a mailing list plus the documentation system or a wiki).

Open anything else pertaining to the specific project

You get the idea by now:

Anything at all related to the project will need to be done in the open.

Once the project is released as open source, it no longer belongs to “you,” the company, and now belongs to “we,” the community (of which the company is a part). This means the community must be included at all points going forward.