Hej! This document is a guide to how and why we contribute to open-source projects within 13|37.
There are three main why's when it comes to working on open-source projects at 13|37. These are:
- Giving back to the community.
- Empowering our employees to learn and grow by working on open-source projects.
- Improving the image of 13|37 in the eyes of future employees and clients.
You will be achieving all of these by working on open-source projects. So let's get right into the how.
The rest of this document is split into two main sections: -For Contributors, and -For Organizers. If you are tasked with contributing to open-source, you should read the former and if you are tasked with organizing open-source work (as a competence group lead or otherwise) you should read the latter.
So, you have decided to join our open-source initiative and grow with us? That is fantastic.
Just to reiterate a few benefits... you will be giving back to the open-source communities which provide us with the tools to be better at our jobs. You will also be contributing to the growing pool of 13|37 employees and improving our public reputation while doing so.
Most importantly, however, you will be growing yourself. Not just by gaining additional skills and honing your existing ones. You will also be growing your brand as an open-source contributor. The strength of your public profile (likely on GitHub) can make or break your next interview.
It is a common misconception that to contribute to open-source projects, one has to code. Not true. Most open-source projects require much more than just code. You can use many other skills to help, such as:
- Design skills (improve styling, UX, branding...)
- Writing skills (documentation, guides, translations...)
- Organization skills (knowledge sharing sessions, events, Q&A help..)
- And of course... Coding skills (resolve issues, review pull requests..)
We encourage all employees, when they have sufficient extra time, to contribute to open-source projects. But especially engineers, when they are between assignments, should consider contributing as one of the higher priorities.
There is a list of projects to which we at 13|37 contribute. If you are currently part of a competence group then the obvious choice should be one of the projects assigned to your competence group (found on the list). In general, you can pick any project from the list. Try to find one that aligns with your skillset and your interests. In any case, you should make this decision together with your manager.
You should first familiarize yourself with what the project does and how it works. This should be written in the project's Readme.md file and presented on its front page (example). Most projects also have some documentation, hosted on a different website and linked from the readme. You should read through that, deploy the project (if applicable) and have a general look around.
After you've familiarized yourself with the project have a look through the open issues of that project (example). There is usually a tagging strategy that marks the types of issues. You should keep an eye out for issues tagged with "good first issue" or "need help". Look through these issues, find one that you understand and would like to resolve.
Then "claim" the issue by commenting on it saying something like "I would like to resolve this issue".
You can also look through the pull requests of a project (example). This will give you insight into the codebase and the coding standards.
Before you ask your question be sure to do your homework. See if the question has already been asked by googling it. Also, look through the documentation if the answer lies within.
If you cannot find the answer on your own you should reach out for help. Before posting a question I recommend reading this guide on how to ask a coding question well.
To reach out you can:
- Message a colleague who is on the project.
- Comment on the issue you've taken.
- Write to the forum (if there is one).
- Open a new issue on the project.
- Write directly to the project maintainers.
You submit contributions via pull requests. This might be less familiar to our non-engineer colleagues. Put simply a pull request is a request to accept some changes that you have made to a project.
Projects generally have a set of contribution guidelines that state what a pull request should contain. Be sure to follow this when submitting a pull request.
It is usually better to open a pull request early on, so others can watch or give feedback on your progress. Make sure to mark the pull request as WIP - work in progress if you do so.
Here are the steps to make a change and submit a pull request on GitHub:
- Fork the repository and clone it locally.
- Create a branch.
- Make your changes.
- Reference your issue in the title or description. (example. Closes #37)
- Push your changes (same article as above)
Now keep your eyes open for reviews and address any comments. When your pull request receives comments you should address them by replying or by adjusting your code and updating your pull request.
We want to keep track of how many hours our employees spend working on open-source projects. This is why we ask you to log your time under the TODO: INSERT PROJECT project in Visma.
When it comes to code it is always better if you think things through first. Most of the time, a code contribution to an open-source project is a normal and inconsequential task. But sometimes it's more than that. Try to follow these practices:
- We can only contribute code that we have the right to contribute. If you are having doubts, reach out to the Head of Competence Development.
- Don’t contribute code that exposes sensitive or proprietary information.
- Don’t contribute sub-par code. Your contributions are a reflection of your engineering skills. We’d rather take the time and get another set of eyes and do a proper code review.
This section is meant for open-source project organizers. Those who select projects and facilitate contributions to said projects.
The organizers of open-source contributing are Competence Group Leads. You can find the list of all current competence groups here. Each lead must select one or more open-source projects (if applicable) for their respective competence groups.
Employees who are not competence group leads have the opportunity to nominate open-source projects to the leads. The leads must facilitate this process and have the discretion to select the most appropriate projects.
It is important to keep in mind the three main reasons for 13|37 open-source contributions. To reiterate, these are:
- Giving back to the community.
- Empowering our employees to learn and grow.
- Improving the image of 13|37 in the eyes of future employees and clients.
With those in mind, we also have criteria for the best open-source project candidate. An ideal project should:
- Be understaffed.
- Be popular.
- Have potential.
These are the core guidelines for selecting a project. In the following sections, we will go into some detail with more suggestions on how to select a project.
Some projects require contributors to sign a Contributors License Agreement (CLA) before contributions will be accepted.
Most CLAs contain terms that we are okay signing. If you are in doubt contact Head of Competence Development.
Try finding an open-source project with a license LICENSE which has a non-restrictive licensing scheme. These are some of such open-source licenses:
- Mozilla Public License, 1.0, 1.1 and 2.0 variants
- MIT License
- Berkeley Software Distribution (BSD), 3-clause, 2-clause and 0-clause variants
- Apache License, 1.0, 1.1 and 2.0 variants
- Common Development and Distribution License (CDDL)
Some projects do not have a license specified. If you still consider such a project a strong candidate, try reaching out to the maintainers to see if they can add a LICENSE to the project.
Verify that the project you are considering is well documented and easy to pick up. Check that:
- There is clean and maintained documentation. This includes
README,CODE OF CONDUCTand other community standards documents that aid in onboarding. - There is a clear indication that issues can be worked on by anyone. Project maintainers usually mark such issues with tags like
good-first-issue,help-wantedorup-for-grabs.
There are plenty of projects on GitHub which are either dead or are "finished" (no issues or feature requests). This is why you need to take into consideration a project's activity before selecting it. If we want our pull requests to get reviewed and pulled into a project there need to be active maintainers.
To check a project's activity:
- Look at the issues example
- Are there many issues available?
- Are there conversations on issues?
- Look at the pull requests
- Look at the Insights example
- Check the various statistics.
- Are commits frequent and recent?
- Is the code frequency good?
- Check the various statistics.
When deciding what projects to choose, it is important to consider the impact our contributions may produce. Determining impact is usually a multivariate equation. Some of the components that can help you decide are:
- Number of stars the project has earned on GitHub
- Number of downloads (npm, NuGet, ...) or users that the project currently has
- Number of our clients that depend on the software
- Popularity and visibility of the project in different social circles
We want to establish and keep a good relationship with the owners of the projects we contribute to. This has many benefits for both parties. We help the projects by contributing our time and knowledge and the project owners can reward us by giving us more privileges in the project and publicly acknowledging our contributions to the project.
The best way to reach out to the project owners is to start by using and contributing to the project. After some contributions, you can reach out to the project owners to establish a relationship.
Some project owners are open to establishing a relationship even before any contribution is made. When trying this path just be open and transparent about your intentions.
If you need more guidance and a more involved active community in your open-source journey, you might consider working groups. Working groups are much more organized than a set of individuals contributing to a project. Working groups do have specific projects they work on, but the organisation is more people-centric than project-centric. You can google a technology + working group to see if there are working groups for your tech stack, like the Node.js working groups. You can also check out the open-source initiative working groups and these open-source organisations, which also have working groups.
We encourage you to contribute to open-source projects. You don’t need our review and approval for the contribution you make, we’re not here to slow you down.
- Assuming your code is awesome, the project you are contributing to is active, and you don’t anticipate any concerns with the contribution, then contribute to the project.
- If you encounter any conduct issues with the project you are working on (e.g. if anyone in the community engages in misbehaviour toward you or anyone else), please don’t engage in an online spat as these can escalate in non-productive ways.
- If you don't know how to proceed or have any other questions you can contact the Head of Competence Development or your manager.