Navigating the Open Source Community
In the realm of DeFi, where transparency and openness are fundamental principles, being able to independently verify the inner workings of an application is especially critical. For instance, any independent security researcher can audit and assess the security status of an open-source project. This fosters a high level of trust among users and developers alike.
Moreover, the ability for anyone to contribute to the enhancement of the software they use strengthens the connection between developers and cultivates a community around a particular software project.
It’s no wonder these concepts are core to the ethos of Web3 and the broader open-blockchain movements.
Getting Started with the Open Source Community: Key Tips
Are you or your company new to developing an open-source project? Navigating the open-source community can be challenging! There’s a lot to learn about community guidelines and the unique aspects of the tools you’ll need to use.
In this article, we’ll explore the initial steps you should take to maximize the benefits for both your project and the community you’re building around it.
GitHub, the primary platform for open-source code, provides guidelines within every repository.
Let’s take the wemake-python-styleguide project as a case study.
The GitHub checklist includes the following essential items:
- Description
- README
- Code of Conduct (CoC)
- CONTRIBUTING.md
- License
- Issue Templates
- Pull Request Template
In this report, we’ll review each item on the checklist and delve into additional key features that GitHub hasn’t marked as “mandatory” but are still crucial for your project.
Issues and Pull Requests
Issues and Pull Requests are fundamental to any software project. They are the core channels of communication necessary for building a community-driven project. However, effectively managing this communication can be challenging, with many potential pitfalls along the way. Fortunately, there are tools and strategies available to help you navigate these challenges successfully!
Forms and Templates
One of the first challenges developers encounter when dealing with issues is determining what information they need from users to fix a bug or initiate a discussion about a new feature. To streamline this process, GitHub offers issue templates and forms that specify the necessary details. Below are some examples to help you get started:
- Bug Report Form and Template
- Rule Request Template
The key difference between a template and a form is that users can bypass fields in a template, whereas forms can enforce required fields.
Documentation:
- Syntax for Issue Forms
- Configuring Issue Templates for Your Repository
It’s also important to note that you can—and should—attach labels to your templates:
- Name: Rule Request
- Description: Request a new rule to be checked
- Labels: ‘rule request’, ‘feature’
These specified labels are automatically applied to newly created issues, which makes it easier for maintainers to filter and manage different types of issues.
Adding External Links and Creating Templates
You can enhance your “Create new issue” project page by including additional links to external resources. For example, you could link to pages like this GitHub configuration file or this issue creation page. This approach is particularly useful if you want to direct users to existing external resources such as support forums or community Discord servers.
Similarly, you can create a template for Pull Requests. These templates often include a checklist to ensure that all necessary steps have been completed before submitting the code.
Pull Request templates typically align closely with the practical guidelines outlined in your CONTRIBUTING.md file (which we’ll cover shortly), ensuring consistency and thoroughness in the contribution process.
Saved Replies
One of the common challenges open-source maintainers face is dealing with the same discussions repeatedly. To address this, companies can develop standardized responses to recurring issues such as:
- Spam
- Off-topic questions
- Incomplete bug reports
- Bugs that cannot be reproduced
- Feature requests that will not be implemented
To manage these situations efficiently, maintainers can use a private repository where they store and organize pre-approved responses. The process is straightforward:
- A developer identifies a recurring issue.
- They create an entry in the private repository.
- The company reviews and approves the response, then saves it as an easily accessible file.
- The response may also include specific actions, such as deleting a comment or banning a user.
Additionally, some frequently used replies can be saved directly into your GitHub profile for quick access:
For example, here’s a “saved reply” to address spam:
“Hi, it seems like this entry might have been posted by accident, as it resembles spam. If this was a mistake, I’ll delete the entry for now. However, if it was indeed spam, please note that we will have to block your account if you post unrelated content again, as it consumes the valuable time of our open-source contributors.”
Using well-crafted, pre-prepared responses to handle recurring issues can save you time and allow you to focus on more important tasks.
Code Review Best Practices
Conducting code reviews can be challenging, as they require a balance between technical expertise and empathy—especially when your team members come from diverse cultural and linguistic backgrounds. It’s easy to unintentionally make comments that come across as harsh.
To navigate this, I recommend adopting the “Semantic Code Review” approach, which I personally use and advocate for others: Conventional Comments. This method helps clearly convey your intentions, making your feedback during code reviews easier to understand and more constructive.
Best Practices for Code Reviews
Here are some key principles to keep in mind during code reviews:
- Use Empathy: Always consider the feelings and perspectives of others.
- Offer Assistance: Be ready to help your colleagues.
- Express Gratitude: Remember to say “Thank you” and maintain politeness.
- Be Welcoming: Strive to be someone others enjoy working with.
- Automate Where Possible: It’s often easier to receive feedback from automated tools than from people.
- Ask Questions and Suggest Alternatives: Engage in constructive dialogue.
- Share Knowledge: Take the opportunity to both teach and learn from others.
- Critique Solutions, Not People: Focus on the code, not the coder.
Things to Avoid:
- Don’t Assume Everyone Knows What You Know: People have different experiences and knowledge bases.
- Don’t Expect Others to Think and Act Like You: Diverse perspectives are valuable.
- Avoid Personal Criticism or Blame: Keep the focus on improving the solution, not on finding fault.
It’s essential to recognize that how you communicate is just as important as what you communicate. A positive “Tone of Voice” can make a big difference. Here are some resources for guidance:
Following these straightforward principles can enhance your code review process and create a more positive and productive environment for everyone involved.
Code Owners
New contributors often encounter challenges with certain parts of the code but may not know who to reach out to for assistance or review.
By adding a .github/CODEOWNERS file to your repository, you can designate specific users responsible for reviewing particular sections of the application. This is particularly valuable in large projects where different individuals or teams are responsible for different components. You can find the documentation for setting this up here.
Additionally, you can make these reviews “mandatory,” ensuring that code owners must review changes before they can be merged. Here’s an example of how to implement this.
Security
Security issues should never be reported publicly, as doing so could allow malicious actors to exploit the vulnerabilities. Fortunately, GitHub offers essential tools for managing security concerns.
Repository owners should implement the following:
- Security Policy: Create a .github/SECURITY.md file outlining what users should do if they discover a critical security flaw. Typically, this involves contacting a specific email address rather than making the report public. Example.
- Security Advisories: Use this feature to issue CVEs (Common Vulnerabilities and Exposures) for known and resolved vulnerabilities.
- Dependabot Alerts: Enable notifications from GitHub to alert you if any of your dependencies have reported new CVEs.
- Code Scanning Alerts: Automatically generate alerts by using CodeQL, a tool for identifying vulnerabilities in your code.
By following these four steps, you can effectively manage security for your project. Additionally, ensure that you adhere to in-code security best practices and integrate specialized tools into your CI pipeline.
Automation
If a task can be automated, it probably should be! GitHub Apps and Actions are vital for automating the management of issues and pull requests. You can utilize existing automation tools or even create your own. For example:
- Stale Bot: Automatically closes old and inactive issues and PRs. Example.
- CLA Bot: Ensures contributors sign a Contributor License Agreement (CLA) before submitting code. Example.
- Issue Label Bot: Automatically adds relevant labels to issues. Example.
- Reviewer Lottery: Automatically selects a reviewer for PRs based on specific criteria or at random. Example.
- Custom Automation: Create your own workflows using GitHub Actions or Danger. Example.
Handling Unwanted Behavior
Now, let’s shift our focus to the people involved, as your community project cannot thrive without its users. Working with people can be challenging, and conflicts are an unfortunate reality.
Luckily, there are established guidelines to help prevent and resolve conflicts when they arise. These guidelines, known as the “Code of Conduct,” are invaluable. It’s no surprise that most major open-source projects have already adopted one.
Examples of effective Codes of Conduct:
Additional Resources:
- Orientation: GitHub, mailing lists, conferences.
Why Is It Considered Effective?
- Detailed Examples of Undesirable Behavior: A good Code of Conduct (CoC) provides comprehensive examples of unacceptable behavior, often based on past incidents. This ensures the rules are clear and cover a wide range of scenarios.
- Public List of Violations: Transparency is maintained through a publicly accessible list of violations, such as the one provided by Python: Python Code of Conduct Bans.
- Open Problem Discussion: Issues are discussed openly within the community, as seen in forums like this discussion on recent CoC events.
- Adaptation to Various Communication Channels: A good CoC is versatile and can be adapted to different forms of communication within the community.
- Broad Coverage and Application: Effective Codes of Conduct address a wide range of issues and are applicable across diverse open-source communities. They benefit from extensive real-world experience and have undergone multiple revisions to improve their effectiveness.
- Organizational CoC: It’s also worth noting that a single CoC can be created for all projects within an organization, streamlining guidelines across the board. For example, Python’s organizational CoC serves all its projects.
Inclusive Language in Code
An essential aspect of creating a welcoming environment for your project is using inclusive language throughout your codebase. This includes variable names, comments, configuration options, and more. Adopting inclusive language helps foster a more diverse and inclusive community.
For helpful guidelines on this topic, you can refer to Google’s Inclusive Code Guide.
README.md
Your README.md file serves as the gateway to your project. It’s the first thing visitors see, so making a strong first impression is crucial.
A well-crafted README.md should include:
- Clear Purpose: Explain the project’s goals and objectives.
- Demo or Code Examples: Provide examples to illustrate how the project works.
- Next Steps: Offer guidance on what users can do next, such as how to get started or where to find more information.
An example of an effective README.md can be found here.
There are various styles, guides, and templates available online to help you create a great README.md. You can choose the approach that best suits your needs:
Additionally, you can create a README.md file at the organization level, which can be useful for highlighting shared resources, important links, communication channels, featured projects, support options, and more. Examples include:
CONTRIBUTING.md
Every open-source project has its own set of guidelines and processes for contributions. But how can a newcomer know what to do in each case?
That’s where the CONTRIBUTING.md file comes in!
This file outlines everything a contributor needs to know to successfully submit a pull request (PR). The content can range from very straightforward, like this example, to more comprehensive and detailed, like a full guide:
When creating your own contributing guide, aim to:
- Ensure Clarity: Clearly outline the steps contributors need to follow.
- Provide Depth: Address common issues and challenges contributors might face.
- Be Practical: Include specific commands or snippets for key tasks like releasing, running tests, or building.
A good CONTRIBUTING.md file often details the exact process for creating a PR, including what to include and what to avoid. It may also provide rules for core developers, such as guidelines on merging branches or renaming commits during squashing. For example, see Mypy’s CONTRIBUTING guide.
Having a well-crafted CONTRIBUTING.md file can make it significantly easier to attract and onboard new contributors to your project.
Licenses
Licensing can be complicated, and it’s crucial to seek extensive legal advice from a specialized lawyer to choose the right license for your specific project and jurisdiction. Key considerations include:
- Use in Private Projects: Can your code be utilized in private, proprietary projects?
- Patent Issues: Can others use your code to develop and patent their own technologies?
- Service-Based Usage: Is your code allowed to be used as a service by other companies (e.g., database-as-a-service)?
If you’re unsure, you might find services like Choose a License helpful. The most commonly used licenses include MIT, BSD, Apache, and GPL.
Releases
Once your code is written, and the pull requests have been reviewed and merged, it’s time to prepare a release. Storing release information in your project’s repository is essential for several reasons:
- Community Engagement: Keeping the community informed about new releases is crucial. GitHub offers a “Releases only” subscription, which is useful for users who want to stay updated.
- Technical Documentation: Releases should include details about technical changes, such as updates to the API, ABI, plugins, or build processes—anything that developers might find important.
- Clarity for Users: Without clear release documentation, users may struggle to understand what has been released, which version is current, and what changes have been made.
GitHub provides built-in tools for managing tags and releases. Here are some examples:
- Tags: View Tags
- Releases: View Releases
A popular method for tracking changes is the use of a CHANGELOG.md file, following the format outlined in Keep A Changelog.
Versioning
Deciding how to generate the next version number is another important consideration. There are several versioning systems to choose from, listed here by popularity and applicability:
For those interested, there’s also an option to automate the generation of CHANGELOG.md and the creation of releases directly from commit messages using tools like semantic-release. However, this is entirely optional and based on personal preference.
Additionally, GitHub’s Package Registry and GitHub Container Registry can be integral parts of the release process. These registries not only serve as technical repositories for caching and intermediate artifacts but are also official platforms for publishing releases.
Discussions
If your repository receives a high volume of questions regarding its use, you have two main options:
- Create a Dedicated Tag on StackOverflow: This is viable if you have someone with the necessary reputation to establish and manage the tag.
- Enable GitHub Discussions: This allows for in-platform discussions directly alongside your repository.
The decision often depends on where the activity is already happening. If conversations have started on StackOverflow, it makes sense to continue them there. Conversely, if discussions are happening on GitHub, there’s no need to shift them to another platform.
In some cases, people use GitHub Discussions for handling support questions and brainstorming new features, while reserving GitHub Issues specifically for reporting bugs.
Final Thoughts
We’ve explored many of the key tips to help you begin your open-source journey, from submitting ideas to releasing the final implementation. But this is just the beginning!
Creating and nurturing a thriving open-source community demands a wealth of knowledge, passion, empathy, and commitment. Engage with other maintainers, learn from their experiences, contribute to larger projects, and absorb as much as you can from them.
And most importantly, don’t forget to enjoy the process.