Navigating The Challenges Of Modern Open-Source Authoring: Lessons Learned
smashingmagazine.com
This article is a sponsored by StoryblokOpen source is the backbone of modern software development. As someone deeply involved in both community-driven and company-driven open source, Ive had the privilege of experiencing its diverse approaches firsthand. This article dives into what modern OSS (Open Source) authoring looks like, focusing on front-end JavaScript libraries such as TresJS and tools Ive contributed to at Storyblok.But let me be clear:Theres no universal playbook for OSS. Every language, framework, and project has its own workflows, rules, and culture and thats okay. These variations are what make open source so adaptable and diverse.The Art Of OSS AuthoringAuthoring an open-source project often begins with scratching your own itch solving a problem you face as a developer. But as your experiment gains traction, the challenge shifts to addressing diverse use cases while maintaining the simplicity and focus of the original idea.Take TresJS as an example. All I wanted was to add 3D to my personal Nuxt portfolio, but at that time, there wasnt a maintained, feature-rich alternative to React Three Fiber in VueJS. So, I decided to create one. Funny enough, after two years after the librarys launch, my portfolio remains unfinished.Community-driven OSS Authoring: Lessons From TresJSContinuing with TresJS as an example of a community-driven OSS project, the community has been an integral part of its growth, offering ideas, filing issues (around 531 in total), and submitting pull requests (around 936 PRs) of which 90% eventually made it to production. As an author, this is the best thing that can happen its probably one of the biggest reasons I fell in love with open source. The continuous collaboration creates an environment where new ideas can evolve into meaningful contributions.However, it also comes with its own challenges. The more ideas come in, the harder it becomes to maintain the projects focus on its original purpose.As authors, its our responsibility to keep the vision of the library clear even if that means saying no to great ideas from the community.Over time, some of the most consistent collaborators became part of a core team, helping to share the responsibility of maintaining the library and ensuring it stays aligned with its original goals.Another crucial aspect of scaling a project, especially one like TresJS, which has grown into an ecosystem of packages, is the ability to delegate. The more the project expands, the more essential it becomes to distribute responsibilities among contributors. Delegation helps in reducing the burden of the massive workload and empowers contributors to take ownership of specific areas. As a core author, its equally important to provide the necessary tools, CI workflows, and clear conventions to make the process of contributing as simple and efficient as possible. A well-prepared foundation ensures that new and existing collaborators can focus on what truly matters pushing the project forward.Company-driven OSS Authoring: The Storyblok PerspectiveNow that weve explored the bright spots and challenges of community-driven OSS lets jump into a different realm: company-driven OSS.I had experience with inner-source and open-source in previous companies, so I already had a grasp of how OSS works in the context of a company environment. However, my most meaningful experience would come later, specifically earlier this year, when I switched my role from DevRel to a full-time Developer Experience Engineer, and I say full-time because before taking the role, I was already contributing to Storybloks SDK ecosystem.At Storyblok, open source plays a crucial role in how we engage with developers and how they seamlessly use our product with their favorite framework. Our goal is to provide the same developer experience regardless of the flavor, making the experience of using Storyblok as simple, effective, and enjoyable as possible.To achieve this, its crucial to balance the needs of the developer community which often reflect the needs of the clients they work for with the companys broader goals. One of the things I find more challenging is managing expectations. For instance, while the community may want feature requests and bug fixes to be implemented quickly, the companys priorities might dictate focusing on stability, scalability, and often strategic integrations. Clear communication and prioritization are key to maintaining healthy alignment and trust between both sides.One of the unique advantages of company-driven open source is the availability of resources:Dedicated engineering time,Infrastructure (which many OSS authors often cannot afford),Access to knowledge from internal teams like design, QA, and product management.However, this setup often comes with the challenge of dealing with legacy codebases typically written by developers who may not be familiar with OSS principles. This can lead to inconsistencies in structure, testing, and documentation that require significant refactoring before the project can align with open-source best practices.Navigating The Spectrum: Community vs. CompanyI like to think of community-driven OSS as being like jazz musicfreeform, improvised, and deeply collaborative. In contrast, company-driven OSS resembles an orchestra, with a conductor guiding the performance and ensuring all the pieces fit together seamlessly.The truth is that most OSS projects if not the vast majority exist somewhere along this spectrum. For example, TresJS began as a purely community-driven project, but as it matured and gained traction, elements of structured decision-making more typical of company-driven projects became necessary to maintain focus and scalability. Together with the core team, we defined a vision and goals for the project to ensure it continued to grow without losing sight of its original purpose.Interestingly, the reverse is also true: Company-driven OSS can benefit significantly from the fast-paced innovation seen in community-driven projects.Many of the improvements Ive introduced to the Storyblok ecosystem since joining were inspired by ideas first explored in TresJS. For instance, migrating the TresJS ecosystem to pnpm workspaces demonstrated how streamlined dependency management could improve development workflows like playgrounds and e2e an approach we gradually adapted later for Storybloks ecosystem.Similarly, transitioning Storyblok testing from Jest to Vitest, with its improved performance and developer experience, was influenced by how testing is approached in community-driven projects. Likewise, our switch from Prettier to ESLints v9 flat configuration with auto-fix helped consolidate linting and formatting into a single workflow, streamlining developer productivity.Even more granular processes, such as modernizing CI workflows, found their way into Storyblok. TresJSs evolution from a single monolithic release action to granular steps for linting, testing, and building provided a blueprint for enhancing our pipelines at Storyblok. We also adopted continuous release practices inspired by pkg.pr.new, enabling faster delivery of incremental changes and testing package releases in real client projects to gather immediate feedback before merging the PRs.That said, TresJS also benefited from my experiences at Storyblok, which had a more mature and battle-tested ecosystem, particularly in adopting automated processes. For example, we integrated Dependabot to keep dependencies up to date and used auto-merge to reduce manual intervention for minor updates, freeing up contributors time for more meaningful work. We also implemented an automatic release pipeline using GitHub Actions, inspired by Storybloks workflows, ensuring smoother and more reliable releases for the TresJS ecosystem.The Challenges of Modern OSS AuthoringThroughout this article, weve touched on several modern OSS challenges, but if one deserves the crown, its managing breaking changes and maintaining compatibility. We know how fast the pace of technology is, especially on the web, and users expect libraries and tools to keep up with the latest trends. Im not the first person to say that hype-driven development can be fun, but it is inherently risky and not your best ally when building reliable, high-performance software especially in enterprise contexts.Breaking changes exist. Thats why semantic versioning comes into play to make our lives easier. However, it is equally important to balance innovation with stability. This becomes more crucial when introducing new features or refactoring for better performance, breaking existing APIs. One key lesson Ive learned particularly during my time at Storyblok is the importance of clear communication. Changelogs, migration guides, and deprecation warnings are invaluable tools to smoothen the transition for users.A practical example:My first project as a Developer Experience Engineer was introducing @storyblok/richtext, a library for rich-text processing that (at the time of writing) sees around 172k downloads per month. The library was crafted during my time as a DevRel, but transitioning users to it from the previous rich-text implementation across the ecosystem required careful planning. Since the library would become a dependency of the fundamental JS SDK and from there propagate to all the framework SDKs together with my manager, we planned a multi-month transition with a retro-compatible period before the major release. This included communication campaigns, thorough documentation, and gradual adoption to minimize disruption.Despite these efforts, mistakes happened and thats okay. During the rich-text transition, there were instances where updates didnt arrive on time or where communication and documentation were temporarily out of sync. This led to confusion within the community, which we addressed by providing timely support on GitHub issues and Discord. These moments served as reminders that even with semantic versioning, modular architectures, and meticulous planning, OSS authoring is never perfect. Mistakes are part of the process.And that takes us to the following point.ConclusionOpen-source authoring is a journey of continuous learning. Each misstep offers a chance to improve, and each success reinforces the value of collaboration and experimentation.Theres no perfect way to do OSS, and thats the beauty of it. Every project has its own set of workflows, challenges, and quirks shaped by the community and its contributors. These differences make open source adaptable, dynamic, fun, and, above all, impactful. No matter if youre building something entirely new or contributing to an existing project, remember that progress, not perfection, is the goal.So, keep contributing, experimenting, and sharing your work. Every pull request, issue, and idea you put forward brings value &mdashp not just to your project but to the broader ecosystem.Happy coding!
0 Comentários ·0 Compartilhamentos ·57 Visualizações