Open Source Guidelines

Open-sourcing software follows Thinking Machines’ values of being a builder and a team player—only this time, within a larger community. Open-source enables us to participate in the larger practice of peer production, and gives us the opportunity to understand our users and co-developers well. To such, there are two main open-source guidelines that we should follow:

• We must strive to write maintainable code. Our codebase should be readable, with appropriate API documentation and README. It should follow standard coding styles or practices, idiomatic, and must be extensible enough to add or modify features.
• We must strive to maintain developer relationships. Relationships are paramount, and as we represent the company, we must ensure that our values reflect how we approach our contributors and collaborators. This can be expressed through Contributing guides, effective governance, and a Code of Conduct publicly declared in our repositories.

Technical Guidelines

We must strive to maintain a baseline quality on our software projects, this goes even outside our open-source work. A well-maintained project says a lot about the company, so we need to exert rigor in keeping our codebase healthy.

On Documentation

Documentation should be given equal priority to a program's business-logic. Remember that when we write documentation, we write for the person next to us.

• README file. This file should contain a description and basic information on the project. For most Git hosting services such as Github/Gitlab, the README file is the first point-of-contact a developer has on our code.

  • A good template for any README file.
  • Some examples of exceptional READMEs.
  • A simple web-application to make your own README

• API Documentation. A well-documented codebase can ease onboarding of outside contributors into our project. If possible, all modules, classes, and methods should be documented. Type signatures should be defined, and sample usage must be written. Your favorite language should have its preferred way of generating documentation: for Python it’s Sphinx, for Java it’s JavaDocs, etc.

  • Sphinx package for generating API documentation
  • WriteTheDocs' learning resource for writing code documentation

• Contributing Guide. Outside contributors may not be aware of how we setup our development environment and workflows. All of these should be expressed inside a Contributing Guide.

  • Github guide on writing contributing guidelines
  • Mozilla’s learning resource for drafting contributing guidelines

• Releases and CHANGELOG. All releases should be documented in a file called CHANGELOG.md. It should narrate how the codebase evolved throughout patch, minor, and major releases. Versions should be listed in reverse chronological order, written for humans, and follows a sensible format.

  • Guide on keeping a changelog from the Changelog podcast
  • A Javascript package for automatically generating Changelog from tagged releases

On Code

Code is the core of our project and if left unkempt (especially with multiple contributors from multiple backgrounds, coding styles, etc.), might grow into an unmaintainable mess. Open-source software also demands a certain rigor in writing code.

• Write idiomatic code that adheres to the community style guide. External contributors may also work with our project, thus, we need to adhere to a style guide set by the community (e.g. for Python, it is PEP 8). Your favorite language should have one.

  • PEP 8: Style Guide for Python Code
  • A list of style guides for various languages

• Automated testing. As our codebase grows, we need to ensure that we are scaling responsibly. This entails shipping robust and well-tested code. A good set of test cases can give us more confidence when updating several parts of the codebase (or during refactors). In this regard, it is important that every project we open-source is accompanied by some form of test suite. Your favorite language should have its own test suite, so you should definitely check that out.

  • If possible, it is highly-recommended to use test coverage as a metric for a well-tested codebase. Usually, it provides a percentage of all lines in the codebase that were run in the test suite. Of course, quality is better than quantity and smarter tests should be written.

• Continuous Integration/Deployment (CI/CD). Perhaps one of the most crucial aspects in open-source software is the idea of continuous integration and deployment. Because multiple collaborators (internal/external) are now working on the project, we have to ensure that every commit is well-integrated and verified automatically.

Community Guidelines

Once a project is open-sourced, we should expect that Issues and Pull Requests will come from the community. As representatives of the company, we should act in the most professional way as possible. Below are guidelines that should codify how we would relate to our co-creators.

• Add a Code of Conduct. Explicitly stating a Code of Conduct in every repository assures external contributors that we are working with good intentions. At the same time, a Code of Conduct helps us protect ourselves. Contributors can interact with us in a variety of ways, and some might have unproductive behavior towards the project. A Code of Conduct demonstrates that we are serious in taking action when needed, and that all processes will be fair and transparent.

  • Code of Conduct can be manifested as a separate file, CODE_OF_CONDUCT.md found in every repository. We can adopt common templates such as the Contributor Covenant, but it may be better to write our own.
  • Here is a comprehensive guide on how to enforce and take appropriate action with respect to the Code of Conduct.
  • Remember, the main idea is that we want to encourage the behavior we want to see in the world. We want our projects to be welcoming and friendly. If our environment is toxic and hostile, we can lose contributors and affect the attitude towards our project as a whole.

• Communicate our expectations via a Contributing Guide. Internally, we have our own system of naming branches or wording commits. If we want a consistent codebase, we should be able to relay our expectations to contributors. At the same time, the contributors should also be informed of their expectations from us: that we will get into their PRs for X number of days, that we will give thorough and helpful code reviews, etc.

• For larger projects, drafting a Project Vision and a Roadmap is important. One common problem in larger projects is receiving tons of feature requests. These are helpful, because we can get a sense of what our users need. However, without a clear roadmap, our product might “lose its way.” There’s an art that we need to master in terms of balancing what the community needs and what we should/can deliver.
• Give back! Help First-Time Contributors make their first foray into OSS! There are several ways to help first-time contributors make into their first foray into open-source software. This includes adding "first-timers-only" tags in our Issues, signal-boosting issues during Hacktoberfest, and registering our projects to beginner-friendly platforms such as Code triage. It’s a good way to attract and help new contributors in their open-source journey.
  • In addition, we should be more patient with first-time contributors in our project. Some things that may be second nature to us, creating Pull Requests, navigating git, etc., may be not as apparent for them.
• Automate using Github bots. This part is helpful during style checks. Instead of sounding very nitpicky during code reviews, it’s better to have an “objective” bot that performs these reviews. This enables us to focus more on the logic and structure of the code instead of its code style.
• Above all, empathy. Contributors can come from different backgrounds, you can have beginners to skilled professionals. Accommodate them as possible and be patient and understanding. Enforce rules for unproductive behavior if need be. The spirit of open-source is collaboration: we tap a wide range of talent, we listen to the crowd, and we distribute a sense of ownership to our open-source projects.

Some tricks and tips

• Take advantage of Github bots, you can use a bot that onboards first-time contributors, a stale bot that closes stagnant issues and PRs for X time period, and Travis checks for code style, unit testing, and code coverage.
• When someone reports a very easy Issue, ask them if they want to open a PR on that. Sometimes, some people will report issues or bugs in our code (maybe a misspelling in the docs, some weird behavior, etc.). If this bug is not critical, we can ask them first if they want to open a PR on that. This can attract them to contribute into our project more!
• Hacktoberfest! There’s such thing in Github as Hacktoberfest, where almost everyone is inching to find a project to contribute to. If we have easy Issues, we can tag them as “hacktoberfest” for signal-boosting.
• Take care of contributors. It’s easy to get contributors in a project, but most of these contributors are drive-by (they’re gone after 1 PR). The best way to take care of them is to give them ownership to a part of the project!
• Use external chat clients such as Gitter. If the project is large enough (many contributors, a lot of users, questions here and there), we can open up a chat client so that it’s easier for them to reach us.