Open Source Guides
repository·main·Indexed 12 days ago
https://github.com/github/opensource.guideA collection of community-curated resources and best practices for managing and contributing to open-source software projects. It provides guidance on running projects, establishing accessibility standards for web interfaces and CLI tools, creating accessibility statements, and documenting project vision and maintainer expectations.
What's inside Open Source Guides
- Open Source Guides (https://opensource.guide/) provides a collection of curated resources designed for individuals, communities, and companies to learn how to effectively run and contribute to open-source projects. The content aggregates community best practices rather than promoting specific vendor-driven methodologies.
What is Open Source?
mainAn open source project is one that anyone can freely use, study, change, and distribute for any purpose. These permissions are granted via an open source license.
Key characteristics include:
- Reduced barriers: Lowers friction for selection and collaboration, allowing rapid distribution and improvement.
- User control: Unlike closed-source software, users can control the code (e.g., a company can hire someone to modify the software rather than relying solely on a vendor).
- FOSS/FLOSS terminology: The terms 'Free Software' and 'Open Source' are often used interchangeably. In the context of FOSS (Free and Open Source Software) or FLOSS (Free, Libre, and Open Source Software), 'free' refers to liberty/freedom (libre) rather than just zero cost (gratis).
Managing commercial involvement in open source projects
mainWhen contributors are paid by corporations or receive compensation for their work, it is important to treat commercial activity as a normal part of project development.
Key principles for managing commercial contributors:
- Evaluate by technical merit: Paid developers should not receive special treatment; every contribution should be assessed based on its technical value.
- Focus on contribution, not motivation: When discussing the project, focus on the quality and quantity of the contribution rather than the external factors (like payment) that enable it.
- Commercial is compatible with Open Source: Using open source code as part of a commercial offering or service is a standard practice and does not conflict with the open source nature of the project.
How to handle conflicting project visions using forks and plugins
mainWhen a contributor's needs or opinions conflict with your project's core vision, use these strategies to maintain project direction while supporting the community:
- Encourage forking: Remind users that forking is a core strength of open source. If a user has a 'unicorn' use case that doesn't fit the 80% use case you cater to, encourage them to maintain their own fork.
- Convert the tool into a platform: Instead of adding every requested feature to the core, provide APIs, customization hooks, or a plugin system. This allows users to build the specific solutions they need without bloating the main codebase.
Working with language or ecosystem-specific foundations
mainIf your open source project is closely tied to a specific programming language or ecosystem, you may be able to work with an existing software foundation dedicated to that ecosystem. These foundations provide support and infrastructure for related tools and frameworks.
Examples:
- Python Software Foundation: Supports PyPI (the Python package manager).
- Node.JS Foundation: Supports frameworks like Express.js.
Maintainer responsibilities for Code of Conduct enforcement
mainAs a maintainer, you are the enforcer of the rules established in your Code of Conduct. Your responsibilities include:
- Fair Review: Provide a thorough and fair review of every complaint. If a report does not constitute a violation, communicate this clearly to the reporter and explain why.
- Address 'Edge Cases': Even if a behavior doesn't technically violate the CoC, if it makes participants uncomfortable, you should investigate. You may need to revise the CoC for clarity or speak to the individual about skirting the boundaries of expected behavior.
- Set Standards: You are responsible for shaping the community values and ensuring they are enforced in an even-handed way.
Is Open Source always free?
mainWhile most open source projects are free of charge, 'free' is a byproduct of the license rather than a requirement of the definition. Because an open source license allows anyone to legally copy and redistribute the project, charging for the software itself is difficult.
However, projects can still generate revenue while remaining open source through methods like:
- Dual Licensing: Offering the software under different licenses for different use cases.
- Feature Restrictions: Limiting certain functionalities in the open source version while offering them in a paid version.
Establish project brand through communication and code style
mainYour project's brand is shaped by how you write and how you code:
- Communication Style: The tone used in READMEs, guides, community documents, and issue responses is part of your brand. A polite, helpful, and professional tone creates a welcoming atmosphere for new contributors. Aim for simplicity, especially for non-native English speakers.
- Code Style: Consistent coding styles and clear naming conventions for functions, methods, and variables act as part of your brand. While strict style guides (like those used by
AngularorjQuery) aren't mandatory for beginners, establishing a predictable style helps attract and retain contributors.
Understand open source governance models
mainThere are three common governance structures used in open source projects. Choosing one depends on your project's goals and complexity.
1. BDFL (Benevolent Dictator For Life)
One person (usually the original author) has the final say on all major project decisions. This is common in small projects or those created within a company. Example: Python.
2. Meritocracy
Formal roles in decision-making are granted to active contributors who demonstrate "merit." Decisions are typically made through consensus-based voting. In this model, contributors represent themselves rather than their employers. Example: Apache Foundation projects.
3. Liberal Contribution
Influence is based on current work rather than historical contribution. Major decisions are made through a consensus-seeking process (discussing core claims) to encompass as many community viewpoints as possible, rather than direct voting. Example: Node.js, Rust.
Each model has distinct advantages and trade-offs. You can explore specific templates for BDFL or Meritocratic models to help define your own.
Identify formal roles in open source projects
mainOpen source projects often use specific roles to distribute responsibility and recognize contributions. While you can define these however you like, common roles include:
- Maintainer (суправаджалы): Individuals who feel responsibility for the direction of the project and strive to improve it. This role is not limited to writing code; it can include documentation, promotion, or community management. In some projects, maintainers are the only ones with commit access.
- Contributor (удзельнік): Anyone who adds value to the project. This includes commenting on issues or pull requests, fixing bugs, writing code, or organizing events. Even someone who simply comments on a pull request is a member of the community.
- Committer (правіцель): A role used to distinguish those who have specific write access (commit access) to the codebase from other forms of contribution.
Common open source governance structures
mainThere are three primary models for how decisions are made in open source projects:
- BDFL (Benevolent Dictator for Life): A single person (often the original author) has the final say on all major decisions. This is common in smaller projects or those originating within a company.
- Meritocracy: Decision-making power is granted to active contributors who demonstrate "merit." Decisions are typically made via voting consensus. In many meritocratic models (like the Apache Foundation), contributions must be made by individuals, not by corporations.
- Liberal Contribution: Influence is based on current work rather than historical contributions. Major decisions are made through a consensus-seeking process that strives to include as many community perspectives as possible, rather than a pure vote (e.g., Node.js, Rust).
Distinguish between public GitHub repositories and open source licenses
mainMaking a GitHub repository public is not the same as licensing it.
GitHub's Terms of Service allow others to view and fork your public repository, but they do not grant permission to use, distribute, or modify your work in other projects. To make your project truly open source and allow others to use or contribute to it, you must include an explicit open source license.