Best practices in a collaborative environment

Tue 03 April 2018 by Akshita Gupta, Aditya Arora

This blog post is made possible due to amazing mentors Dustin, Eli, Hassan and, Emma.

This is a place for all newcomers to Open Source to get an idea for getting started with version control systems and contributing to Open Source projects. It is totally different in maintaining your own projects as compared to working with multiple people in order to create a single great product.

As an Outreachy aspirant, I have been working for the past two months, solving multiple issues in Mozilla's Taskcluster and Diversity projects. They have awesome mentors who have been really helpful in making me understand my mistakes. I want to share these practices with everyone in order to skip those mistakes.

1. Welcome to Open Source

If you are a newcomer, I want to welcome you to this one-of-a-kind great place called as OpenSource . It is a place to showcase your work and at the same time help others to make awesome projects. Remember, Every organisation is different. They have their own set of standards and rules to follow. In this blog post, however, I would like to give you a general introduction and practices which covers most of the organisations.

1.1 Getting Started

Firstly, go through the organisations' Github pages and look through the repositories. Find out those which interests you. Once you have selected a repo

Go through the README and understand the working of the project.
Follow the instructions in the README and set up the project on your local machine.
Explore the project's codebase. If you find any error or bug, generate an Issue.
If you are unable to find anything, somebody else might have. Go to the Issues tab of the project to find some issues being worked upon.

Don't know coding and still want to contribute? Don't be disheartened. Let's get our facts correct- A human being cannot learn every programming language. You might be good at writing. There are various projects that need an incredible writer like you. You can always look for the Documentation tag in an Issue or generate a new one in case you find a repo that needs documentation. You can also learn while contributing. I believe, the logic of all the programming languages is similar. The major difference lies in the syntax. If you know how the project works, the syntax should not be an obstacle in your path.

1.2 Forking the repo

You cannot make changes directly to the organisation's repo. For that, you need to make a copy into your own profile. Click on the button to get your own copy of the repository.

1.3 Cloning the repo

You can now clone the repo in a local system to make the changes. Type

git clone https://github.com/<your-username>/<repo-name>.git

in bash to get the repository on your computer.

2. Working on issues

You might have found a bug or want to work on an Issue that interests you. If you found a bug, go through the tab to see if an issue is already generated or not. If not, you may generate a new issue.

2.1 Asking to get assigned

Make sure you ask for permission from the mentors before working on an issue as there might be other people who could already be working on that issue. A simple message such as

Hey, I want to work on this issue. Is it already assigned?

will do the work.

2.2 Wait for the response

You have to understand that people live in various parts of the world and have different timelines. They might be having a holiday which might be a working day in your country. Also, they might be working on multiple projects. You must take care of all the factors and should not keep messaging in order to get a reply.

2.3 Make your changes

Once you get the approval from a mentor, go ahead and make the changes as per the issue. Don't make any unnecessary changes. Examples are - Introducing new lines. - Removing and adding spaces. - Changes other than the assigned issue. - Changing the workflow of the project.

These should be evaluated first before making a commit.

3. Getting Stuck

As a newcomer, it is obvious that you might get stuck at a place where you might not understand what is going wrong. Don't panic .Others might have also faced similar issues.

3.1 Checking versions

If these are the cases, follow the README in the repo to correct your mistakes. Make sure you are on the right version as that told in the repository. - There might be certain dependencies which only work on a specific Operating System. - Certain functions could be deprecated or renamed in newer versions of a library. - The programming language might follow newer syntax rules as compared to previous versions.

3.2 Searching for a solution

Others who got the same problem could have asked on the web for a solution. In most cases, you might get the remedy on StackOverflow. A good practice is to try to solve the problem and if you are unable to, copy the exact error in Google and look for the solutions.

3.3 Asking the mentors

This should be the last resort and make sure you do this only after you have followed the above two steps and done an extensive research but are still unable to get a remedy for your problem. Generate a message containing - The problem you are facing. - What solutions you have tried. - Links to solutions you have tried. - Relevant screenshots.

Value their time. Don't ask irrelevant questions as they are giving you, their time by answering your query. It can be a bit annoying for the reviewers if you ask unnecessary questions which might already be on Google.

4. Pull requests

When creating a Pull Request (also called a PR), there are certain practices which give better results.

4.1 Add your files

If you are working on a single issue, you can use

git add .

However, this is not suggested for multiple issues and you should only add the desired files for which changes were required using

git add filename.py

4.2 Squashing your commits

One PR needs one commit. Squash all your commits into a single commit.

Remember, Branching is the key to avoid all the commit problems.

git checkout <branch name>

Merging 5 commits to a single commit.

git rebase -i <branch name>~5 <branch name>

At the Interactive screen, choose fixup for commit 2 / 3 / 4 / 5.

git push -u origin <branch name>

Commit Related issues? If you have any issues regarding commits, go ahead and see this post.

4.3 Generating a Pull Request

Separate PRs should be generated for different issues. If not, they get mixed and create a ruckus when everything is done on the master branch. In order to create better PRs, it is recommended that you should create PRs on a branch which could be named as solves-issue-21. This not only helps in working on multiple issues simultaneously but also makes the collaborator at the other end, understand what the PR does.

4.4 Creating a new branch

Add a new branch for pushing our changes to an issue.
```
git checkout -b <branch-name>
```
If required, rebase your branch even to master by following the rebase steps
Push the changes to your repo.
```
git push origin <branch-name>
```

5.Rebasing your repository

5.1 What is a Rebase?

Rebasing is changing the base of your branch from one commit to another making it appear as if you'd created your branch from a different commit.

5.2 Why is it needed?

The forked repository is few commits behind.
Newly created branch is not even with the master branch.

5.3 How to rebase?

Check current configured forked repository
```
git remote -v
```

Set new remote repository that will be synced

git remote add upstream <original-github-repo-link>

Check new upstream repository
```
git remote -v
```
Fetch the original Github repository
```
git fetch upstream
```
Rebase the commits
```
git rebase -i upstream/master
```
Push the changes
```
git push -f
```
Rebase commits against a specific branch and then proceed with Step 6
```
git rebase -i <branch-name>
```
Rebase commits against a specific node and then proceed with Step 6
```
git rebase -i HEAD~<commit-number>
```