Skip to content
This repository has been archived by the owner on Feb 1, 2019. It is now read-only.

Latest commit

 

History

History
135 lines (93 loc) · 8.46 KB

contributing-to-a-project.md

File metadata and controls

135 lines (93 loc) · 8.46 KB

Identifying Need

In a nutshell

The first and foremost thing to do when joining a project is to figure out what needs to be done for the project at the present time. Identifying what tasks need to be accomplished is the best way to identify how to have an immediate and helpful impact on a project as a contributor.

Reviewing onboarding material

When coming on to a new project, the best place to start is by reviewing any onboarding material. Commond places to find onboarding material for a project include:

  • README.md
  • CONTRIBUTING.md
  • Project wiki

These locations often include information on how to get up and running with a development environment, common workflow practices, locations of issue trackers, wikis, documentation, etc, and other information which may be necessary in order to make contributions to the project.

Talking to active project members

Ideally, a project should have up-to-date and readily available onboarding materials for a new contributor to review. Unfortunately though, not all projects have this information documented and published. In cases such as these, it's best to reach out to current contributors to the project. Even when this documentation does exist, it may be necessary to reach out to active contributors to ask clarifying questions, correct outdated information, or just to say hello so they know who they are working with!

Communicating activity

In a nutshell

Being a good contributor means not leaving project teammates guessing. It is important that all team members understand what each other team member is actively doing (or not doing) so that team members can avoid stepping on each other's toes, while still ensuring everything that needs to be done is done.

What your are working on

Being a good contributor means letting the team know when starting work on a new task. There are never too many channels to keeping teammates in the loop! If the task is in the issue tracker being used by the team (which it definitely should be), always self-assign the task when working on it, and even inform the team via the regular communication channel, whether that be a chat channel or an email thread. Keeping the team aware of what tasks are being worked on not only helps the team avoid duplicating efforts, but also encourages the team to see tasks being worked on.

What you are no longer working on

Being a good contributor means letting the team know when work on a task has stopped or stalled. Sometimes things come up; a task can be blocked by another task, a teammate may no longer have time to work on a task, or may be simply burned out from working on a task they don't like. Under these circumstances, a contributor should always let their teammates know that the task is no longer being worked on, so that everyone is aware that it will need to be picked up and worked on by someone else. If the task is being tracked in the project issue tracker (which it definitely should be) always make sure to unassign the task so that no teammate believes it is still being worked on.

When you've done a thing

A lot of (personal) time gets invested in contributing to an open source project. Be proud of every little thing that gets accomplished! Whenever a task is accomplished or something is done for the project, let the team know via the regular communication channels (e.g., chat or email chain). Letting teammates know about accomplishments not only keeps them in the loop about what does or does not remain to be done, but helps encourage them by showing that the project is making progress! This may be one of the most underrated aspects of being a helpful contributor. If the task is being tracked in the project issue tracker (...you get the idea), always make sure to mark it as completed to keep the view of the project status current.

Your hopes and dreams!

Investing time in helping to make a project happen means that you are part of that project! As a part of that project, you shouldn't be shy about speaking up about your vision for its future and its mission. It's important to also remember that your vision isn't the only one, but contributing your opinions is important in order to continue feeling invested in the project and its mission.

Being a good citizen as a technical contributor

As a technical contributor, it is important to abide by the contribution guidelines of the project. There are some general guidelines as well which will improve the quality of contributions to any project, and make the contributions more easily digestible by teammates.

Atomic commits and PRs

Every commit should have a specific focus and scope, and should not include work being done outside of that scope. This idea of ensuring that each commit remains small with all changes within the commit being related to one another can be more concisely referred to as and "atomic commit". Constructing commits this way makes them easier to review for teammates and makes them simpler to perform git operations on.

Documentation

New code should always be documented! This is a general coding best practice, but comes into particular focus when working on open source projects where new contibutors may frequently come and go. Contributing well documented code makes it simple for new contributors to quickly and easily understand work which has been previously done. Also, it makes it easy for current contributors to remember how things work when they come back to them months later!

Collaborative brainstorming

When trying to solve problems, it's always a good idea to brainstorm with teammates and backboard ideas off of them. Not only does this give the whole team a sense of ownership over each problem which has been solved in the course of working on the project, but also helps teammates understand a solution before it is even implemented. This will also make reveiwing contributions easier for teammates, and makes it more likely that teammates will find the solution agreeable when it is time for them to review it.

Becoming a non-technical contributor

In a nutshell

Writing the code is one small part of gaining success as an open source project. Most of the work done on a project is actually non-technical. This section includes some examples of non-technical work which every project needs done in order to succeed.

Managing task definition, assignment, and progress

I.e.,, project management. A successful project will have a good road map, and a good road map will consist of tasks. Every project needs someone who can help make sure tasks are getting the attention they need, make sure it is known by everyone who is working on a given task, and check in with teammates on how tasks are progressing to ensure the status of a task in the issue tracker reflects reality.

Managing project needs/resources

Another project management need, every project needs someone who can help make sure that there is enough expertise and help on the team to accomplish the tasks which need to be accomplished by the deadline which they need to be completed by.

Facilitating discussion

Sometimes getting the conversation is the hardest part of collaborating. Every project needs someone who is willing to jump in head first and kick start a discussion between collaborators when they seem all to willing to remain quiet.

Maintaining focus on the mission

Technically minded contributors can often times become distracted by minutiae, such as what software library to use to solve a specific problem or whether the code base should be written out using tabs or spaces. It is extremely helpful for every project to have someone who can interject when these nitpicky conversations go on too long or dominate the discourse too much to remind the team of the end goal of the project, and remind them that the success or failure or the project's mission almost certainly does not rely on the outcome of these debates.

Evangilism

A project is only as helpful as the number of people it can reach. Every successful project needs contributors who can help spread the word about the project, and can help get it into the hands of the people who will find it the most useful.

Opening up feedback channels for users

Just as a project is only as good ad the number of people it can reach, it is also only as good as the ability of its users to wield it. Every successful project needs people who are reaching out to and talking to users to determine how helpful or useful the project is in its current state, and gathering feedback on how it could be more useful or helpful.