This article is intended to serve as a reference so that you can understand everything you need to be proud of your repository and make your open source project more open. By using open standards, an open source project improves its quality and shareability, since such standards exist to foster better communication between creators and consumers of the project. Most importantly, open standards can guide technology development by gently enforcing space for diversity and equity.
What is open source?
The term open source started in the late 80's as a way to guarantee access to technological development by legally guaranteeing the right to copy, modify, and redistribute software. This idea has expanded and today it is about fostering a culture of sharing that supports everything from political actions to a billion dollar technology industry.
The projects and their communities, which give the projects their value, have become much more complex than just the code. Today, it is impossible to think of a project outside of what I prefer to define as its ecosystem. "Ecosystem" sounds to me like a proper definition, because it acknowledges the complexity of technical things, like code and configuration, and also of people.
Lack of diversity is a problem in open source
Without open source, the technology industry would collapse, or it wouldn't even exist. That's the scope of importance that open source has today. What a powerful feeling it is to know that we are all "standing on the shoulders of giants"? We are all benefiting from the power of the commons, using collective labor and intelligence to make something better for everyone.
What's rarely spoken of is that such important initiatives, in most cases, depend solely on the volunteer labor of its maintainers. This creates a huge imbalance, both from work and diversity aspects.
Open source is intrinsically a power to foster diversity within the development industry by valuing the contributions of what is contributed over who is contributing it. The reality is, though, that free time is often a rare commodity for many people. Many people are too busy working to generate income, caring for families and loved ones, looking for work, fighting social injustice, and are unable to dedicate time to contribute to software.
The very opportunity to contribute to the system depends on you being one of the lucky ones who can be part of this system. This is not a reality for many others because of their gender, skin color, or social status. Historically, women accumulate unpaid work that's invisible, but which requires a substantial proportion of their energy and time. Underprivileged people have little free time because they have to work more hours, often having more than one job.
This is reflected in the numbers. Only 4.5% of open source maintainers are not white males, according to research into the field. So we know that this billion dollar industry, shaping technological development, is composed of a homogeneous environment. But we also know that diversity renders robust innovative results.The question is, how can this be changed?
Intentional communication with your open source community
Communication is key. Build a structure with transparency of communication and governance for your project. Clear, concise and respectful communication makes your project accessible to users and contributors. It helps project maintainers devote their time focusing on what they need to do. It helps interested people feel welcome and start contributing faster and more consistently, and it attracts diversity to your community.
Sounds great, but how can this be obtained? I grouped the rules of good practice into three categories procedural, daily, and long term. These practices are in part strategic, but if you and your community don't have the capacity to be strategic, it's also possible to substantially change your project by adding a few simple files to your repository.
But which files are those, and what happens when you already have several projects under your management? A few of them are:
- Code of conduct
- License
- Readme
- Changelog
- Contributing
- Ownership
- Test directory
- Issues
- Pull request templates
- Security
- Support
To help you get started, there are many projects that offer templates. By simply cloning them, you create a repository with these documents.
Another tool, designed to help open source software (OSS) maintainers and open source program offices (OSPO) is check-my-repo. Created by us at Sauce Labs' OSPO Community, it's an automated tool built on Repolinter that verifies whether the main necessary parameters to comply with open source best practices (including the files mentioned above and a few other rules), are present in your repositories. The web app also explains why each file needs to exist.
Procedural best practices
As the name implies, this is about the process:
- Maintain a single public issue tracker.
- Allow open access to the issues identified by the project.
- Have mechanisms for feedback and to discuss new features.
- Offer public meeting spaces scheduled in advance and have them recorded.
Here are some files that relate to the procedural logic:
- README: Make it easier for anyone who lands on your project to get started.
- Code of conduct: Establish expectations and facilitate a healthy and constructive community.
- Ownership: Make sure that someone is put in charge of the project to prevent it from being forgotten.
Daily tasks
This is about the day-to-day aspects, including:
- Check the status of the project.
- Explain how to submit issues, propose enhancements, and add new features.
- Show how to contribute to the project.
Files related to the daily aspects of project management are:
- Contributing: A step by step guideline on how to contribute.
- Changelog: Notable changes need to be logged.
- Security: Show how to report a security vulnerability.
- Support: How the project is being maintained.
Long term goals
This has information that guarantees the history and continuation of the project, such as a mission statement, key concepts and goals, a list of features and requirements, and a project roadmap.
Relevant files are:
- License: It's essential for users to know their limits, and for you to protect yourself legally.
- Test directory: Use this to avoid regression, breaks, and many other issues.
Creating and maintaining your open source project
Now imagine a project with all of these factors. Will it help you build and keep a community? Will noise in communication be mitigated? Will it save maintainers tons of time so they can onboard people and solve issues? Will people feel welcome?
Creating and maintaining an open source project is very rewarding. Creating collaboratively is an incredible experience and has the intrinsic potential to take such creation into possibilities that one person alone, or a small group could never achieve. But working openly and collaboratively is also a challenge for the maintainers and a responsibility for the community to ensure that this space is equitable and diverse.
There's a lot of work ahead. The result of surveys on the health of open source communities often reflect the worst of the technology industry. That's why ensuring that these standards are used is so important. To help mitigate this situation, I am betting on standards. They're a powerful tool to align our intentions and to guide us to an equitable, transparent, and shareable space. Will you join me?
Comments are closed.