top of page
Search

How to Build Open Source Software Developers Actually Want to Use

  • Writer: Ran Isenberg
    Ran Isenberg
  • 1 day ago
  • 7 min read
How to Build Open Source Projects Developers Actually Want to Use
How to Build Open Source Projects Developers Actually Want to Use

Open source isn't just about sharing code — it's about creating a product developers trust, use, and contribute to. With over 650,000 downloads and more than 800 GitHub stars across my open-source projects, I've learned what makes a repository thrive. Whether you're launching a company-wide OSS initiative or sharing tools as an individual contributor, success depends on quality, maintainability, and community experience.

In this post, you will learn the principles, best practices, and GitHub CI/CD automation needed to build open-source projects that are secure, easy to contribute to, and genuinely useful.

Table of Contents

Open-Source Success Core Guidelines

As developers, we strive to integrate only the best, secure, and easy-to-use open source projects into our workflows. Therefore, as open-source maintainers, we must conform to the same high standards that we expect from others, and even exceed them.


Or in other words, developers want to use open source projects that are:

  1. Well maintained & High Quality

  2. Provides capabilities users actually want

  3. Easy to use - Good DevEx

  4. Secure

  5. Easy to contribute code


*This blog post establishes the principles and standards for creating [Your company name here] open source repositories that developers want to use and contribute to.

I will write this post from the point of a company - "YourCompany", but most of the principles are relevant to individuals too.

Well Maintained & High Quality

YourCompany's open-source project should be treated as a first-class product, with developers as its primary customer persona.

As such, it represents the company and shapes its perception in the eyes of its users, the developers who interact with it.

It must meet the same production-grade standards we uphold in your on-premises and SaaS offerings.

Let's review the standards below.


Dedicated Maintainers

Each project requires dedicated maintainers who are responsible for reviewing pull requests, responding to issues, and ensuring the project remains current with evolving technologies.

Maintainers should be easily reachable and responsive to community feedback.

Maintainers should subscribe to receive notifications for new issues, PRs, or community discussions and respond within a defined timeline (up to two weeks, depending on the issue type - security immediate, feature request, bug, etc.).

This policy needs to be set across all projects and refined by YourCompany's management.


Regular Updates and Dependency Management

Projects must receive regular updates, even when no major features are being added.

This includes updating dependencies through tools like Dependabot on a weekly basis, addressing security vulnerabilities identified by Snyk, and supporting new runtime versions as they become available.


Semantic Versioning and Release Notes

All GitHub releases must follow semantic versioning principles and include comprehensive release notes that clearly explain what changed, what was fixed, and any breaking changes that might affect users.

Use GitHub auto-generated capabilities with the addition of YourCompany's technical writers adding feature examples and guidelines. This is a manual process.


SDLC

The project will follow the same principles and CI/CD pipeline steps that you use for your internal libraries or services.


Build → lint/code quality/unit test → deploy to test environment → integration test/e2e tests → merge → publish library → publish documentation → manual release notes


Multiple quality gates must be implemented, including linting, security scanning, unit tests, integration tests, and end-to-end tests. Code coverage requirements should be enforced to maintain high testing standards.

The pipeline should test against multiple cloud environments (deployment step) and library runtimes (Python 3.9,3.10,3.11 etc.) to ensure broad compatibility.

Here's my SDLC for reference in two projects:

 

As for the publish documentation step, the GitHub documentation is updated after merge and after the library has been published. Publishing can refer to:

  1. NPM/Pypi

  2. AWS marketplace

  3. AWS public ECR gallery

  4. Any other public interface/registry

Provides Capabilities Users Actually Want

Treat it as a regular product. Provide each open source project a dedicated product manager who will regularly gather feedback from users to understand their needs, preferred runtimes, integration requirements with YourCompany products, and desired workflows.

 

Community Engagement

  1. Publish RFCs for new features as GitHub issues to get feedback and votes from customers. This allows the community to provide input and ensures that new features address real user needs rather than theoretical requirements.

  2. Use GitHub projects to describe road map, surveys for new features. Users want to understand where the project is headed, whether it's a POC or YourCompany has longer terms plans for it. Transparency is key!

  3. Maintain active engagement with the community through GitHub issues, discussions, and other communication channels. Respond to questions and issues promptly and professionally.

  4. Actively work to build and nurture communities around YourCompany open source projects. This includes participating in relevant conferences, webinars, writing blog posts, and engaging with users on social media.


By following these guidelines, YourCompany open source projects will attract more users, receive more contributions, and ultimately provide greater value to both the community and YourCompany's business objectives.


DogFooding

YourCompany teams should actively use their own open source projects internally. This validates the software's utility and helps identify issues before they affect external users.

YourCompany teams can test preview versions of the projects.

 

Measure Adoption

Implement telemetry and special headers that track version usage and feature adoption. This data helps prioritize development efforts and identify which features provide the most value to users.

Easy to Use - Good DevEx

This might be the most important guideline of them all. If the DevEx isn't good, it doesn't matter that the project is well maintained.


Simple UX & Governance

When designing APIs and interfaces, always consider the user's perspective. The interface should be intuitive, well-documented, and follow established conventions that developers already understand.

This section requires a follow-up guide on specific YourCompany API/SDK tips.

YourCompany's SDKs/libraries should have the same "look & feel".

Following the suggested guide for UX while using a GitHub template for your open source projects can make sure YourCompany's open source projects are aligned, for example, for Python:

  1. Internal implementation is placed under the _internal folder

  2. Init files expose only the bare minimum (no internal implementation)

  3. Every public function has a docstring

  4. Force users to pass arguments as key=value

  5. Define a maximum number of arguments (keep it short)

 

Documentation

Good documentation is built upon two components: a README file and GitHub pages, where the second expands the first.

Readme file:

A short and simple document that has the following elements:

  1. What the project aims to solve

  2. How does it solve it

  3. Short code examples

  4. Links for more comprehensive guides to getting started/edge cases/etc. on GitHub pages

  5. License link

  6. Contribution/security issue reporting link

  7. Badges, see image below (informative, community links, supported runtimes, version, and latest release version)

 

GitHub Pages

Use GitHub Pages (e.g., with MkDocs) to automatically publish documentation directly from your repository. Documentation should be versioned, maintained as part of the repo, and updated through the CI/CD pipeline.


GitHub Documentation Best Practices:

  • Code Examples include comprehensive, working code examples with all relevant imports. Every example must be linted and tested as part of the CI pipeline to ensure accuracy and functionality.

  • Real-World Use Cases. Show realistic usage patterns, including customer-like scenarios. Include:

    • How to import the module

    • How to use it in practice

    • How to debug issues

    • How to test locally (mock parts of it, when required)

    • How to open a GitHub issue

  • Developer Experience. Use line highlighting in examples to draw attention to key logic.

    Keep the documentation clear, concise, and easy to navigate. See example at https://ran-isenberg.github.io/aws-lambda-handler-cookbook/best_practices/logger/

Secure

Projects must receive regular security updates, even when no major features are being added. 

This includes updating dependencies through tools like Dependabot on a weekly basis, addressing security vulnerabilities identified by Snyk, and supporting new runtime versions as they become available.

In addition, we should run tools like gitleaks and other code analysis tools to cover both 3rd party dependancies and library code.

Every new dependency requires legal approval.

All access to the repository is done via YourCompany's GitHub organization and user permissions set by IT.

Easy to Contribute Code

A successful open-source project thrives on clear contribution pathways and a welcoming developer experience. To lower the barrier for new contributors and maintain high-quality code, follow these practices:


Contribution Guidelines

  1. Provide a clear and concise CONTRIBUTING.md file, inspired by examples like:

Include steps for:

  • Cloning the repo

  • Setting up the environment

  • Running tests and linters

  • Submitting pull requests

    2. Add LICENSE.MD - consult with legal team.

 

Local Development Setup

Provide a Makefile or setup script to easily:

 

Issues and Pull Requests

  • Use a short and friendly issue template to encourage contributions.

    • Feature request templates

    • Security issue

    • Documentation

    • Bug report

  • Label issues with tags like:

    • good first issue

    • help wanted

    • bug, feature, security, docs

  • Enforce a consistent issue and PR format:

    • Each PR must link to a tracked issue.

    • Issue/PR titles should follow the format 'type: information'. Types can include: feature, fix, security, docs, etc.

Open-Source Template

Just as internal automation improves consistency across YourCompany, open source initiatives can benefit from a well-defined template.

Since each open source project requires a complete SDLC, it's best to maintain language-specific templates (e.g., Python, C++, etc.) to ensure quality, governance, and development efficiency. The template includes all the elements described in this blog post.

Here's my cookiecutter template project for reference: https://github.com/ran-isenberg/cookiecutter-serverless-python

 

Suggested Development Flow of a New Open Source Project

Developer portal → GitHub.com → Template scaffolding as private repo → public repo once version is ready.


Developer opens the developer portal. Goes to the self service page and selects the form for creating a new open source. Once all fields are inserted, the automation begins, a scaffolfing starts.

The end result is a private repository on YourCompany's GitHub.com organisation.

Once the library is ready to be released, the developer can manually change its visibility to public.

Summary

Creating successful open-source projects takes more than publishing code — it requires treating your repository like a production-grade product.

In this post, I shared the principles, workflows, and SDLC practices, and product state of mind that you need to have in order to create a project that your customers, the developers, would want to use.

bottom of page