Locked History Actions

DeepZot/CollaboratorGuide

DeepZot Collaborator Guide

Getting Started

The DeepZot software packages are hosted at GitHub. You will need to create a GitHub account or use an existing account to contribute updates to DeepZot.

Fork A Repo

To fork a project, navigate to the project's GitHub page and click the "Fork" button. For this tutorial, we'll be using the baofit project.

CollaboratorGuide1.png

Clone Your Fork

You've successfully forked the baofit project, but so far it only exists on GitHub. To be able to work on the project, you will need to clone it to your local machine.

Run the following code:

git clone https://github.com/username/baofit.git
# Clones your fork of the repo into the current directory in terminal

Configure Remotes

When a repo is cloned, it has a default remote called origin that points to your fork on GitHub, not the original repo it was forked from. To keep track of the original repo, you need to add another remote named upstream:

cd baofit
# Changes the active directory in the prompt to the newly cloned "baofit" directory

git remote add upstream https://github.com/deepzot/baofit.git
# Assigns the original repo to a remote called "upstream"

Workflow

Create Branches

Branching allows you to build new features or test out ideas without putting your main project at risk. We recommend using one branch per new feature / bugfix so that they can be tested and deployed independently.

Pick a short phrase describing what the new branch will provide and Turn_it_into_a_branch_name, then create your new branch locally:

git checkout -b Implement_new_feature_x
# Creates a new branch called "Implement_new_feature_x" and makes it the active branch

To switch between branches, leave out the -b option:

git checkout master
# Makes "master" the active branch

git checkout Implement_new_feature_x
# Makes "Implement_new_feature_x" the active branch

You should *never* change the master branch (on either github or your local computer) since any such changes would need to be abandoned the next time you update from the upstream source.

Push Commits

Once you've made some commits to your local clone, you can push them to your forked project hosted on GitHub. To push commits from the branch Implement_new_feature_x, use:

git push origin Implement_new_feature_x

Pull Requests

Pull requests let you tell others about changes you've pushed to a GitHub repository. Once a pull request is sent, interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.

Initiate The Pull Request

Navigate to your repository with the changes you want DeepZot to pull and press the Pull Request button.

CollaboratorGuide2.png

Pull requests can be sent from any branch or commit but it's recommended that a topic branch (such as "Implement_new_feature_x" from above) be used so that follow-up commits can be pushed to update the pull request if necessary.

After pressing the Pull Request button, you are presented with a preview page where you can enter a title and optional description and see exactly what commits will be included when the pull request is sent.

Review the diff of all changes by switching to the Files Changed tab.

Once you've reviewed the commits and file changes to be sent, press the Send pull request button.

The DeepZot developers will receive an email notification and see the new pull request in their dashboard the next time they log in.

Your pull request will automatically be closed when the DeepZot developers merge your branch upstream. At this point you should pull in the upstream changes to your forked master (see instructions below).

Pull Request Discussion

After reviewing the basic description, commits, and cumulative diff, the DeepZot developers may have questions or comments. Perhaps the coding style doesn't match project guideline, or the change is missing unit tests, or maybe everything looks great and some props are in order. The discussion view is designed to encourage and capture this type of discussion.

The discussion view starts with the pull request's original title and description and then captures additional activity to display chronologically from there. Any of the following types of activity are captured as they happen:

  • Comments left on the pull request itself.
  • Additional commits pushed to the pull request's branch.
  • File and line notes left on any of the commits included in the pull request's range.

Pull In Upstream Changes

If the original repo you forked your project from gets updated, you can add those updates to your fork by running the following code:

# Fetch changes from the official repo
git fetch upstream

# Merges any changes fetched into your local master branch
git checkout master
git merge upstream/master

# Push the changes back to your remote github repo
git push origin master

If you get an error about upstream not being defined, refer back to the "Configure Remotes" section above.