OmbuLabs Open Source Guidelines
Recently we have been thinking about what guidelines we should follow when starting a new open source project, and also about how to organize and keep track of the ones we contribute to.
This article will give you some tips on keeping those open source projects organized, and also how to start them off on the right foot.
Creating new Open Source projects.
When creating a new OSS project these are some important things to include in the README.
Description of the Project
A good description of the project can help users quickly decide if the project would be a helpful addition to their toolset.
Steps on how to Setup the Project.
In this section we should describe the steps needed to get a project up and running. This could include:
- External Dependencies of the project
- Any task runner command to setup external services
- Instructions to run automated tests
- Setup configuration files
- Environment variables
A contributing guide.
In this section we should document standards and steps to contribute to the project, some common things to include are:
- Branch naming
- What the main branch is; where feature and hotfix branches should branch off of
- If we are using an issue tracker, how we link the PR with a story or issue
In projects that we create and we dedicate time to, we include the following banners:
Code of Conduct
We want a welcoming, inclusive and harassment free space to contribute, that’s why we decided to include the code of conduct in all our projects.
We choose the MIT license for our projects because it is open source friendly and business friendly.
It allows us to use our code for commercial purposes but it’s also very permissive so other people can also take advantage of what we build.
Contributing to Existing Open Source Projects
Recently we decided it was a good idea to keep most of our open source projects within one of our organizations on Github. Now when we contribute to an OSS project we always fork it to the FastRuby.io organization. One of the reasons we chose our FastRuby.io organization is that everything on it is open source, and therefore we don’t incur any fees when people not on our team contribute to the projects.
These are the benefits that we get from forking Open Source projects to one of our organizations:
Our brand becomes associated with these OSS projects.
Our teammates learn more about these projects, and are more aware when we open pull requests or work on them.
We can keep track of, and use our contributions in the future.
Sometimes contributions take a long time to be merged into the main OSS project. This way we make sure that we include references to our company’s organization.
None of our references will point to a person’s private repository. They will point to one of our company’s forks, this allows employees to work on pull requests with the support of our company.
Starting our Open Source projects off on the right foot with well written READMES, and also keeping our projects organized within our organizations on Github allows us to be sure that we will have ease in contributing to, finding, and keeping track of our OSS projects in the future.