Outlining the structure of your open-source software project

There are numerous ways to start your open source project. You may already have a working product, a team behind it, proper documentation and guides, or you may just have an idea and want to get started. Or, you may have some other setting. This article discusses how your open-source project could grow and mature into a community-driven project. I hope this provides you with some ideas for moving forward with your project or at least gives you some thoughts.

I wrote another article about how to get started contributing to open-source projects. This article, on the other hand, turns the table and looks at how you, as an author, can set up and develop your open-source project and build a community over time. Depending on the size and adoption of your open-source project over time, your project structure and tasks needed to be taken care of change. Let's see what this looks like.

The diagram above shows the tasks that are needed to be taken care of for different sizes of your open-source project. With an increased size and adoption rate, your tasks will change and diversify, and with that, your open-source project structure will have to change to accommodate for this.

I will structure the article after these three phases. Again, take this with a grain of salt. You can also split it into more phases, introduce more differentiation and complexity, or have a different idea of managing and structuring your open-source project overall. That's totally fine. Let's look at what these three phases are.

1. Organizational project structure for a single maintainer open-source project

This stage represents a single maintainer open-source project that may be adopted by the industry, but likely is not yet in use. Not all open sourced projects are outlined to mature further from this stage, so many open sourced projects are and remain in the category.

At this stage, the focus is mainly technical, with the goal of writing code, lightweight documentation, and building the first end-to-end working product.

This stage is often done by a single developer or a small group and might need some lightweight project management on top of what's shown in the diagram. It usually takes more work to set up a separate documentation website, set up project boards, or define epics than it does to give you a structure to drive the project. Be on the lookout for that.

If you see adoption in the industry, people may open issues or reach out. If this is happening, you may already be at the next stage.

2. Organizational project structure with a few contributors

If the project matures, there is usually a working product, but it might be limited and not production ready. However, something is working, and people are noticing your project. You might be so lucky, and folks are already opening pull requests to improve your project's code and documentation.

This phase centers on documentation, laying the foundation for collaborators coming in and pushing to a first production-ready product.

At this point, you should consider investing some effort into a project documentation website, to describe the concepts of the project, some technical depth, how to get started, and what your plans look like with the project moving on. You should also provide information about how others can participate and start contributing to the project, typically described in a CONTRIBUTING.md file. With folks showing up you will start triaging issues, feature requests, and the like. To ensure everyone is on the same page, you should consider structuring your planned work and any open issues on a project board. Don't overdo it and keep it lean since a single board usually can provide depth over different views (roadmap, open bugs, open features) which don't require separate project boards. You should make sure that updates to the code don't break the product, and if they do, the update shouldn't reach the customers. It would be useful to have a CI/CD pipeline, testing infrastructure, and required code reviews from maintainers and volunteers if not already configured.

You may be in the third phase if larger companies use your project and conferences, meetups, podcasts, or blog posts are constantly discussing it.

3. Organizational project structure for a large-scale open-source project

In the third and last stage, your open-source project matured into a big software project with multiple stakeholders, adopters, and a community working on moving the project forward.

This phase is about giving the community ownership of the project so they can take care of it and improve it. You may also need to make sure that the project doesn't lose its original purpose for which it was once created and incorporate product changes to it.

At this point, you may consider donating the project to an open-source foundation to help organize the project, run security scans and move it over under community control. Donating the project will relieve the authors of a lot of organizational work. If the project gets donated, you should adopt their standards and verbiage across the project, if any are defined.

From the project organizational side, moving the project under community control, it's required to define some sort of technical board / technical steering, which gets elected and overlooks the project development process. This group is responsible for driving the project and can introduce changes to the organizational structure. In some projects, a separate advisory board can help this process.

You may like to separate community-related topics from the technical project code and project documentation. Using multiple repositories can be very helpful if your core project code repository has more strict guidelines and security measures, which are necessary but have slow agility in contributing. One focus should be on improving the project's maturity and the user and contributor experience.

Closing thoughts

Note that not every project needs to grow to hundreds of contributors, very, very successful open-source projects can sustain on a smaller scale and don't need all this extra work. This depends highly on the scope of the project.

At a specific even scale as described, the project can become unique on its own, and you lose track of how everything is put together. Kubernetes, for example, is structured in multiple organizations with 236 repositories.

Last, the CNCF has an excellent website page with further information for open-source project maintainers. It describes the challenges you likely face along your project's journey.

That’s it! If you like to reach out, you do so over Slack on the Kubernetes or the CNCF workspaces.