Skip to content

Commit

Permalink
refine the CONTRIBUTING.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@zxwing
zxwing committed Mar 13, 2016
1 parent 1eaf3f3 commit b4c6447
Showing 1 changed file with 23 additions and 25 deletions.
48 changes: 23 additions & 25 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ Contributing to ZStack

Summary
-------
This document covers how to contribute to the ZStack project. These instructions assume you have a GitHub.com account, so if you don't have one you will have to create one. Your proposed code changes will be published to your own fork of the ZStack project and you will submit a Pull Request for your changes to be added.
This document covers how to contribute to the ZStack project. These instructions assume you have a GitHub.com account, please create one if you don't have. Your proposed code changes will be published to your own fork of the ZStack project, and you need to submit a Pull Request for your changes to be added.

_Lets get started!!!_

Expand All @@ -13,12 +13,12 @@ Fork the code

In your browser, navigate to: [https://github.com/zstackorg/zstack](https://github.com/zstackorg/zstack)

Fork the repository by clicking on the 'Fork' button on the top right hand side. The fork will happen and you will be taken to your own fork of the repository. Copy the Git repository URL by clicking on the clipboard next to the URL on the right hand side of the page under '**HTTPS** clone URL'. You will paste this URL when doing the following `git clone` command.
Fork the repository by clicking the 'Fork' button on the top right. After the fork completes, the page will be redirected to the forked repository.

On your computer, follow these steps to setup a local repository for working on ZStack:
Please follow below steps to setup a local ZStack repository:

``` bash
$ git clone https://github.com/YOUR_ACCOUNT/zstack.git
$ git clone https://github.com/YOUR_ACCOUNT/zstack.git (you can find the URL on the page of the forked repository)
$ cd zstack
$ git remote add upstream https://github.com/zstackorg/zstack.git
$ git checkout master
Expand All @@ -30,9 +30,9 @@ $ git rebase upstream/master
Making changes
--------------

It is important that you create a new branch to make changes on and that you do not change the `master` branch (other than to rebase in changes from `upstream/master`). In this example I will assume you will be making your changes to a branch called `feature_x`. This `feature_x` branch will be created on your local repository and will be pushed to your forked repository on GitHub. Once this branch is on your fork you will create a Pull Request for the changes to be added to the ZStack project.
You need to create a new branch to make changes, and do not directly change the `master` branch. In the following example, We assume you are going to make changes to a branch `feature_x`, which is created in your local repository and will be pushed to the remote forked repository later. Once the branch is pushed, you can create a Pull Request to the ZStack project.

It is best practice to create a new branch each time you want to contribute to the project and only track the changes for that pull request in this branch.
The best practice is to create a new branch each time you want to contribute a patch and only track the changes for that pull request in the branch.

``` bash
$ git checkout -b feature_x
Expand All @@ -42,19 +42,19 @@ $ git add .
$ git commit -a -m "descriptive commit message for your changes"
```

> The `-b` specifies that you want to create a new branch called `feature_x`. You only specify `-b` the first time you checkout because you are creating a new branch. Once the `feature_x` branch exists, you can later switch to it with only `git checkout feature_x`.
> The `-b` is for creating the new branch `feature_x`; it's used the first time you create a new branch.

Rebase `feature_x` to include updates from `upstream/master`
------------------------------------------------------------

It is important that you maintain an up-to-date `master` branch in your local repository. This is done by rebasing in the code changes from `upstream/master` (the official ZStack project repository) into your local repository. You will want to do this before you start working on a feature as well as right before you submit your changes as a pull request. I recommend you do this process periodically while you work to make sure you are working off the most recent project code.
It's important to use `git rebase` to keep an up-to-date `master` branch in your local repository. You need to do this before starting to work on a new feature or making a pull request.

This process will do the following:
This process is like:

1. Checkout your local `master` branch
2. Synchronize your local `master` branch with the `upstream/master` so you have all the latest changes from the project
3. Rebase the latest project code into your `feature_x` branch so it is up-to-date with the upstream code
1. Check out to your local `master` branch
2. Synchronize the local `master` branch with the `upstream/master` so it has the latest changes
3. Rebase the latest changes into the `feature_x` branch to make it up-to-date

``` bash
$ git checkout master
Expand All @@ -64,31 +64,29 @@ $ git checkout feature_x
$ git rebase master
```

> Now your `feature_x` branch is up-to-date with all the code in `upstream/master`.
> Now your `feature_x` branch is up-to-date with `upstream/master`.

Make a GitHub Pull Request to contribute your changes
-----------------------------------------------------
Make a GitHub Pull Request
--------------------------

When you are happy with your changes and you are ready to contribute them, you will create a Pull Request on GitHub to do so. This is done by pushing your local changes to your forked repository (default remote name is `origin`) and then initiating a pull request on GitHub.
Now you are ready to make a pull request. This is done by pushing your local changes to your remote forked repository (default remote name is `origin`) and then initiating a pull request on GitHub.

> **IMPORTANT:** Make sure you have rebased your `feature_x` branch to include the latest code from `upstream/master` _before_ you do this.
> **IMPORTANT:** Make sure you have followed the above chapter to make the `feature_x` branch up-to-date.
``` bash
$ git push origin master
$ git push origin feature_x
```

Now that the `feature_x` branch has been pushed to your GitHub repository, you can initiate the pull request.
To initiate the pull request, do following:

To initiate the pull request, do the following:
1. Open your forked repository: [https://github.com/YOUR_ACCOUNT/zstack](https://github.com/YOUR_ACCOUNT/zstack)
2. Click the new button '**Compare & pull request**'
3. Validate the destination is `master` branch of ZStack and the source branch is your `feature_x` branch
4. Enter a detailed description and click the button '**Send pull request**'

1. In your browser, navigate to your forked repository: [https://github.com/YOUR_ACCOUNT/zstack](https://github.com/YOUR_ACCOUNT/zstack)
2. Click the new button called '**Compare & pull request**' that showed up just above the main area in your forked repository
3. Validate the pull request will be into the upstream `master` and will be from your `feature_x` branch
4. Enter a detailed description of the work you have done and then click '**Send pull request**'

If you are requested to make modifications to your proposed changes, make the changes locally on your `feature_x` branch, re-push the `feature_x` branch to your fork. The existing pull request should automatically pick up the change and update accordingly.
If you are requested to make modifications to your proposed changes, make the changes locally on your `feature_x` branch, re-push the `feature_x` branch to your fork. The existing pull request should automatically pick up the change.


Cleaning up after a successful pull request
Expand Down

0 comments on commit b4c6447

Please sign in to comment.