So you've become a FOSS-Maintainer - Lessons learned from ~6 years of maintaining HedgeDoc

Molly, Erik

Gulaschprogrammiernacht 24 (GPN24) · Day 2 · ZKM Medientheater

Overview

In their GPN24 talk, "So you've become a FOSS-Maintainer - Lessons learned from ~6 years of maintaining HedgeDoc," Molly and Erik deliver a candid and comprehensive look into the multifaceted world of Free and Open Source Software (FOSS) project maintainership. Drawing upon their extensive experience co-maintaining HedgeDoc, a collaborative markdown editor, the speakers demystify the roles and responsibilities that extend far beyond simply writing code. This presentation serves as a crucial guide for current and aspiring FOSS maintainers, shedding light on the often-overlooked challenges and offering practical strategies for sustainable project management.

Watch on YouTube

Visual summary for So you've become a FOSS-Maintainer - Lessons learned from ~6 years of maintaining HedgeDoc by Molly, Erik
Visual summary for So you've become a FOSS-Maintainer - Lessons learned from ~6 years of maintaining HedgeDoc by Molly, Erik

Key moments

  1. 1:00 It's okay to stop maintaining your FOSS project.
  2. 4:20 Planning your own obsolescence as a FOSS maintainer.
  3. 11:00 Creating essential policies for project stewardship.
  4. 17:30 The importance of upstream donations for a healthy ecosystem.
  5. 27:00 Real-world legal pitfalls: copyrighted material on your instance.
  6. 39:00 Overcoming the sunken cost fallacy with troublesome libraries.
  7. 49:00 Remember: you don't owe anyone anything as a volunteer.
  8. 53:00 A call to action: support projects you depend on.

So you've become a FOSS-Maintainer - Lessons learned from ~6 years of maintaining HedgeDoc

Speakers: Molly; Erik

Conference: GPN24

YouTube: https://www.youtube.com/watch?v=UyHTe7xO0jY

Overview

In their GPN24 talk, "So you've become a FOSS-Maintainer - Lessons learned from ~6 years of maintaining HedgeDoc," Molly and Erik deliver a candid and comprehensive look into the multifaceted world of Free and Open Source Software (FOSS) project maintainership. Drawing upon their extensive experience co-maintaining HedgeDoc, a collaborative markdown editor, the speakers demystify the roles and responsibilities that extend far beyond simply writing code. This presentation serves as a crucial guide for current and aspiring FOSS maintainers, shedding light on the often-overlooked challenges and offering practical strategies for sustainable project management.

The talk emphasizes that FOSS maintainership is a complex endeavor, encompassing community management, financial stewardship, legal compliance, system administration, and strategic decision-making, in addition to technical contributions. Molly and Erik share invaluable insights into fostering a healthy project ecosystem, managing volunteer burnout, and ensuring the long-term viability of open-source initiatives. Their discussion is particularly relevant in an era where critical infrastructure increasingly relies on FOSS, making the sustainability and security of these projects paramount.

This article delves into their key lessons, providing a detailed analysis of the technical, organizational, and human aspects of FOSS maintenance. It highlights the importance of proactive planning for maintainer succession, the strategic use of automation, the necessity of robust community interaction, and the often-underestimated legal and financial considerations. Ultimately, Molly and Erik's talk is a powerful call to action for the wider community to support FOSS projects, recognizing the immense effort and dedication required to keep them thriving.

Background

▶ Watch: It's okay to stop maintaining your FOSS project. (1:00)

The landscape of Free and Open Source Software (FOSS) is built on the passion and dedication of volunteers, yet this reliance often creates significant challenges for project sustainability. Many FOSS projects struggle with maintainer burnout, a lack of resources, and difficulties in transitioning leadership, leading to stagnation or abandonment. This problem is exacerbated by the common misconception that maintainership is solely about coding, neglecting the vast array of non-coding responsibilities that are critical for a project's health.

Molly and Erik's journey with HedgeDoc exemplifies this path. Erik initially discovered HedgeDoc as a tool hosted by his university, appreciating its functionality as a collaborative markdown editor. This personal connection evolved into a desire to contribute, starting with small improvements. As is common in FOSS, initial involvement can organically lead to deeper commitment and, eventually, maintainership. Their experience highlights a crucial aspect of FOSS engagement: it often begins with a genuine desire to use and improve a tool that personally resonates with the contributor.

The speakers underscore that involvement in FOSS is not limited to writing code. Contributions can take many forms, such as engaging in community forums, answering issues, providing translations, or helping with documentation. This broader definition of "involvement" is vital for attracting diverse talent and distributing the workload. However, for those already in a maintainer role, the challenge shifts to ensuring the project's continuity, even in their absence. This involves "planning your own obsolescence" by actively seeking and nurturing new contributors, reducing entry barriers, and being transparent about project decisions. Their talk addresses the fundamental question of how to build and sustain a FOSS project that can outlive its initial creators, a critical concern for the entire open-source ecosystem.

Key Findings

▶ Watch: Creating essential policies for project stewardship. (11:00)

Molly and Erik's talk distills six years of HedgeDoc maintainership into several critical findings that challenge conventional perceptions of FOSS development. They emphasize that the role of a maintainer is far more expansive than just writing code, encompassing a diverse set of responsibilities essential for project longevity and health.

  1. Maintainership is Multifaceted: The core finding is that being a FOSS maintainer involves much more than coding. It includes project stewardship (defining scope, making decisions), community management (moderation, outreach), system administration (domains, hosting, CI/CD), legal considerations (copyright, licenses, privacy), and financial management (donations, expenses). This holistic view is crucial for understanding the true demands of the role.
  1. Proactive Succession Planning: Maintainers must "plan their own obsolescence" from the outset. This means consciously designing processes and structures that allow others to easily get involved and eventually take over. Strategies include creating clear contribution guidelines, labeling "good first issues" for newcomers, and actively engaging in community outreach through calls and one-on-one invitations.
  1. Community Engagement and Moderation are Vital: Building a vibrant community requires providing dedicated spaces for interaction (chat, forum) and actively being present through blogs, websites, and social media. However, this also necessitates robust moderation to combat spam and undesirable content, sometimes requiring measures like restricting open registrations. The talk highlighted the success of involving the community in decisions like logo design, which can yield professional contributions and foster strong bonds.
  1. Financial Sustainability Requires Strategy: FOSS projects, despite their volunteer nature, incur costs. The speakers explored various platforms for collecting donations (e.g., Liberapay, GitHub Sponsors) and the decision to form a registered community (Verein) for legal entity and bank account benefits. A key insight is the importance of upstream donations, where projects receiving funds allocate a portion to the core libraries they depend on, fostering a healthier overall ecosystem.
  1. Rigorous Technical Practices are Non-Negotiable: While not just about coding, strong technical practices are fundamental. This includes extensive automation for dependency updates (using tools like Renovate bot or Dependabot with human oversight), comprehensive CI/CD testing to ensure code quality and prevent regressions, and effective issue/pull request management through templates and checklists. Their experience with TypeORM illustrated the sunk cost fallacy when a critical library becomes too burdensome, emphasizing the need for strategic library selection and willingness to replace problematic dependencies.
  1. Legal Awareness and Vulnerability Handling are Paramount: Maintainers are legally responsible for their projects, especially public instances. The case of HedgeDoc's public instance becoming a hub for copyrighted ebooks and casino ads underscored the need for clear usage policies, legal disclaimers, and swift action in response to takedown notices. Furthermore, establishing a documented vulnerability reporting process (security.md), ensuring timely action, and carefully planning the public release of fixes are critical for user trust and project security.

Technical Deep Dive

▶ Watch: Real-world legal pitfalls: copyrighted material on your instance. (27:00)

The technical aspects of FOSS maintainership, as presented by Molly and Erik, go beyond mere coding to encompass robust development practices, strategic tool selection, and proactive security measures. Their insights are grounded in the practical challenges encountered while maintaining HedgeDoc.

Automation and Continuous Integration:

A cornerstone of efficient FOSS maintenance is automation. The speakers strongly advocate for automating repetitive tasks, particularly dependency updates. They recommend tools like Renovate bot, Dependabot, or Update CLI to automatically propose updates to project dependencies. However, a critical caveat is to "keep the human in the loop." While auto-merging patch releases might be acceptable, major or even minor version updates often require manual review to prevent breaking changes or introduce unforeseen issues. Their experience highlights that reviewing these updates can easily consume an entire evening each month, underscoring the need for dedicated time.

Continuous Integration (CI) testing is presented as indispensable. A dedicated test suite with comprehensive tests provides confidence in code changes, especially during dependency updates. If a project breaks, the tests should fail, and any bug found should lead to a new test case. Linting is also crucial for maintaining code quality and consistency. They also cautioned against the "exhaustive test trap," citing HedgeDoc 2's configuration testing, which led to over 5,000 tests that were difficult to maintain and offered diminishing returns. The lesson: test what you need, not every possible permutation.

Effective Issue and Pull Request Management:

To streamline contributions and support, using templates and forms for PRs and issues (e.g., on GitHub, with plans to switch to Codeberg) is highly recommended. These templates can direct users to appropriate channels, such as a community chat or forum for support requests, reserving the issue tracker for actual bugs and feature requests. This prevents maintainers from being overwhelmed by general help inquiries. Crucially, maintainers should "ask people before they submit a pull request or issue" for necessary information like versions used and steps to reproduce, rather than engaging in lengthy back-and-forth communication. A pull request checklist empowers contributors to ensure they've met all requirements (e.g., updated tests, documentation, changelog snippets), reducing the review burden on maintainers.

Strategic Framework and Library Selection:

Choosing external frameworks and libraries is a frequent decision for FOSS projects. The first question, Molly and Erik advise, should always be: "Do you really need a library?" Simple functionalities, like checking for odd numbers, can often be written directly to avoid unnecessary dependencies and their associated "baggage." When a library is necessary, selection criteria include:

  • User base: How many users does it have?
  • Community activity: Star count on platforms like GitLab, last release date, and update frequency.
  • License: Ensure compatibility with the project's license.
  • First impression: "If you're thinking, 'Hmm, I miss this fishy,' it probably is."
  • Code quality: Consider the presence of "cloud MD files" (AI-generated content) as a potential indicator of quality.

They vividly illustrate the sunk cost fallacy with HedgeDoc 2's experience with TypeORM, an Object-Relational Mapper (ORM) for TypeScript. Despite its initial promise, TypeORM updates frequently introduced "catastrophic ways" of breaking the system. The team delayed switching due to the significant investment already made, but eventually realized that "it won't help to invest another day to get it working again." They spent two weeks replacing the library, a decision they advocate making earlier when a dependency consistently causes more problems than it solves.

Versioning Schemes:

Understanding and consistently applying a versioning scheme is vital for both internal development and external users.

  • SemVer (Semantic Versioning): The most common, defining versions as MAJOR.MINOR.PATCH. Patch releases are for bug fixes (no breaking changes), Minor for new functionality (backwards compatible), and Major for breaking changes.
  • RomVer (Romantic Versioning): An intuition-based scheme where Minor indicates backwards-compatible changes, Major indicates breaking changes, and the project version is largely for advertisement (e.g., Firefox's frequent major version bumps).
  • CalVer (Calendar Versioning): Versions based on release date (e.g., YY.MM), often used for applications with regular release cycles (e.g., Ubuntu 26.04 for April 2026).
  • Effort Versioning: Defines versions based on the effort required to deploy an update.

The critical takeaway: "Please choose whatever you want. But please, please, for the love of God, keep it with it. Stick with it." Inconsistent versioning, such as a "patch release that breaks the whole setup," erodes user trust and makes maintenance exponentially harder.

Security and Vulnerability Handling:

For projects that care about security, a documented process is essential. This includes creating a security.md file, making it easy for people to report vulnerabilities (e.g., GitHub security reporting, dedicated email, HackerOne). Key steps:

  • Timely action: Respond as soon as possible, even if just to acknowledge receipt.
  • Verification: Critically evaluate reports, as some might be "AI slop security reports." Templates can help gather necessary information.
  • Release planning: Carefully consider when to release the fix to the public to avoid prematurely disclosing vulnerabilities before users can update.
  • Transparency: Acknowledge known issues (e.g., HedgeDoc 2's readme stating it's "not yet ready for production" and known CSP violations) to manage expectations and reduce redundant reports.

Finally, they emphasize the utility of a release checklist. This standardizes the release process, ensures no steps are forgotten (e.g., creating social media announcements), and significantly speeds up releases. The very last point on any checklist, they humorously add, should always be "update the checklist." This iterative improvement of processes is central to efficient and sustainable FOSS maintenance.

Demo / Proof of Concept

▶ Watch: Overcoming the sunken cost fallacy with troublesome libraries. (39:00)

This talk was primarily an in-depth discussion and retrospective on the practicalities and lessons learned from maintaining a FOSS project, rather than a presentation featuring a live demonstration or proof of concept of specific code or exploits. Molly and Erik focused on conveying their experiences and best practices through narrative and illustrative examples from their work on HedgeDoc.

Defensive Implications

▶ Watch: A call to action: support projects you depend on. (53:00)

While Molly and Erik's talk isn't a traditional cybersecurity presentation, the lessons learned from their FOSS maintainership directly translate into critical defensive implications for any project, open-source or commercial. These insights are vital for securing software, protecting users, and maintaining project integrity.

  1. Proactive Vulnerability Handling is Paramount: The most direct defensive implication is the absolute necessity of a clear and documented vulnerability reporting process. Projects must provide a security.md file detailing how researchers can privately disclose vulnerabilities (e.g., via GitHub security reporting, a dedicated email, or platforms like HackerOne). Crucially, maintainers must ensure timely action—acknowledging reports promptly, verifying their legitimacy (especially given the rise of "AI slop security reports"), and carefully planning the public release of fixes. This controlled disclosure prevents malicious actors from exploiting vulnerabilities before users have a chance to update.
  1. Secure Dependency Management: The emphasis on dependency updates and tools like Renovate bot or Dependabot is a key defensive strategy. Keeping dependencies current mitigates known vulnerabilities in upstream libraries. However, the caution to "keep the human in the loop" for major and minor updates is critical. Automated merging of significant updates without review can introduce new vulnerabilities, breaking changes, or even supply chain attacks if a malicious update slips through. Defenders must implement policies for manual review of non-patch dependency updates, including scrutinizing release notes and performing security audits.
  1. Robust CI/CD and Testing for Security: Comprehensive CI/CD testing with a dedicated test suite serves as a vital defensive layer. While primarily for functionality, tests can (and should) be written to cover security-sensitive areas, preventing regressions that could reintroduce vulnerabilities. Linting enforces coding standards, which often indirectly contributes to security by catching common pitfalls (e.g., unhandled errors, insecure patterns). The "exhaustive test trap" warning also applies here: focus testing on critical paths and security controls rather than attempting to test every permutation, which can be resource-intensive and dilute focus.
  1. Vigilant Code Review and Contribution Policies: The warning to "be cautious. Not everyone has good intentions" during code review is a direct defensive measure against malicious contributions. Open-source projects are susceptible to attackers attempting to inject malware or backdoors. Maintainers must exercise due diligence, especially with external contributions, by reviewing code for suspicious patterns, obfuscation, or unnecessary permissions. Clear contribution rules and code of conduct also set expectations, deterring bad actors and fostering a secure community environment.
  1. Legal Awareness and Instance Security: The experience with HedgeDoc's public instance being misused for copyrighted ebook downloads and casino advertisements highlights significant legal and security risks. Public-facing FOSS instances become attack surfaces. Defenders must:
  • Implement clear terms of service and privacy policies to define acceptable use and manage legal responsibility.
  • Establish robust moderation for user-generated content (forums, chats, file uploads) to prevent the hosting or distribution of illegal content, malware, phishing links, or other undesirable material. This may involve technical controls (e.g., content filters, bot detection) and human oversight.
  • Be prepared for legal takedown notices and have a swift response plan, as such incidents can quickly escalate and damage reputation.
  • Carefully consider the scope and security posture of public instances, potentially restricting usage to non-production or demonstration purposes to mitigate legal and security liabilities.
  1. Community Moderation for Threat Prevention: Providing community spaces like chats and forums is beneficial, but they also require moderation to prevent their misuse. Spam, phishing attempts, and the spread of misinformation or malicious links are common threats. Implementing moderation policies, using automated bots, and having human moderators are essential defensive strategies to protect the community from various forms of social engineering and technical attacks.

By integrating these defensive strategies into their maintenance practices, FOSS projects can significantly enhance their security posture, protect their users, and ensure the long-term integrity and trustworthiness of their contributions to the open-source ecosystem.

Key Takeaways

  • Maintainership is Multidimensional: Beyond coding, FOSS maintainers juggle project stewardship, community management, legal compliance, financial responsibilities, and system administration.
  • Plan for Maintainer Succession: Proactively reduce entry barriers for new contributors and foster a culture where maintainers can transition out gracefully, ensuring project longevity.
  • Strategic Automation with Human Oversight: Leverage tools like Renovate bot and Dependabot for dependency updates, but always retain human review for non-patch releases to prevent regressions or security issues.
  • Robust Community and Legal Awareness: Actively moderate community spaces, establish clear usage policies for public instances, and understand legal responsibilities regarding copyright and data privacy to protect the project and its users.
  • Intentional Library Selection and Versioning: Critically evaluate external dependencies, be willing to replace problematic libraries (avoiding the sunk cost fallacy), and consistently apply a chosen versioning scheme (e.g., SemVer) to maintain user trust.
  • Prioritize Maintainer Well-being: Recognize that FOSS work is often volunteer-based; it's crucial to set boundaries, avoid burnout, find collaborators, and remember that you don't owe anyone anything, ensuring personal and project sustainability.

About the Speaker(s)

Molly and Erik are experienced FOSS maintainers for the collaborative markdown editor HedgeDoc. Their talk at GPN24 draws directly from their approximately six years of hands-on experience in managing and developing the project. They share insights into the full spectrum of responsibilities that come with maintaining a FOSS project, from technical development to community engagement, financial management, and legal considerations. Their presentation reflects a deep practical understanding of the challenges and rewards of sustaining open-source software.

Reviews

Dr. Zero (Offensive Security Researcher) — SOLID

Honest, grounded retrospective on FOSS maintainership that covers the full scope of the job—legal, financial, community, burnout—without pretending it's just about code. Nothing novel for anyone who's been in the trenches, but a genuinely useful onboarding doc for new maintainers or contributors who haven't yet realized what they're signing up for.

Heather Calloway (CISO) — SOLID

Practical, experience-grounded guidance on the operational realities of running a FOSS project — community, legal, financial, and burnout risks. Useful for anyone whose organization depends on open-source maintainers or is considering sponsoring projects, but stays at the practitioner level without connecting to enterprise risk frameworks or supply-chain governance.

→ Top-rated talks at Gulaschprogrammiernacht 24 (GPN24)

All talks from Gulaschprogrammiernacht 24 (GPN24)