From f46167aed9a196bf20587ec3bacad0139abdc96b Mon Sep 17 00:00:00 2001 From: Pushpesh Sharma Date: Mon, 5 May 2014 19:53:49 +0530 Subject: [PATCH 1/8] Dev_guide updated with github workflow I tried to club the information scattered over the internet,and made it suit to our need.These are the resources i used: 1. https://help.github.com/articles/fork-a-repo 2. https://help.github.com/articles/using-pull-requests 3. https://help.github.com/articles/set-up-git 4. https://help.github.com/articles/checking-out-pull-requests-locally Signed-off-by: Pushpesh Sharma --- doc/markdown/dev_guide.md | 152 ++++++++++++++++++-------------------- 1 file changed, 70 insertions(+), 82 deletions(-) diff --git a/doc/markdown/dev_guide.md b/doc/markdown/dev_guide.md index d4e7157..36942f7 100644 --- a/doc/markdown/dev_guide.md +++ b/doc/markdown/dev_guide.md @@ -1,15 +1,11 @@ # Developer Guide ## Development Environment Setup -The workflow for Gluster-Swift is largely based upon the -[OpenStack Gerrit Workflow][]. +The workflow for SwiftOnFile is largely based upon the +Github WorkFlow. ### Account Setup -Gluster for Swift uses [Gerrit][] as a code review system. Create an -account in [review.gluster.org][], then generate and upload -an [SSH key][] to the website. This will allow you to upload -changes to Gerrit. Follow the the information given -at [GitHub Generating SSH Keys][] if you need help creating your key. +You can create a free account on github.It would be better to create keys and add your public key to github, else you can provide username/password each time you communicate with github from any remote machine.Follow the the information given at [GitHub Generating SSH Keys][] if you need help creating your key.You have to create a fork of [swiftonfile repo][] for your development work.You can create your fork from the github Web UI. ### Package Requirements Type the following to install the required packages: @@ -37,67 +33,46 @@ git config --global user.name "Firstname Lastname" git config --global user.email "your_email@youremail.com" ~~~ -### Download the Source -The source for Gluster for Swift is available in Github. To download -type: - +### Clone your fork +You can clone the fork you created using github Web UI.By convention it will be called 'origin'. ~~~ -git clone https://github.com/gluster/gluster-swift.git -cd gluster-swift +git clone git@github.com:/swiftonfile.git +cd swiftonfile ~~~ -### Git Review -Before installing pip, make sure you have pip installed. Install the -python `pip` tool by executing the following command: - +### Add upstream repo +You can add swiftonfile project repo, to get the latest updates from the project.It will be called upstream by convention. ~~~ -sudo easy_install pip +git remote add upstream git@github.com:swiftonfile/swiftonfile.git ~~~ -The tool `git review` is a simple tool to automate interaction with Gerrit. -It is recommended to use this tool to upload, modify, and query changes in Gerrit. -The tool can be installed by running the following command: - +You can confirm these setting using 'git remote -v' it should give you somthing like this: ~~~ -sudo pip install --upgrade git-review +origin git@github.com:/swiftonfile.git (fetch) +origin git@github.com:/swiftonfile.git (push) +upstream git@github.com:swiftonfile/swiftonfile.git (fetch) +upstream git@github.com:swiftonfile/swiftonfile.git (push) ~~~ -While many Linux distributions offer a version of `git review`, -they do not necessarily keep it up to date. Pip provides the latest version -of the application which avoids problems with various versions of Gerrit. - -You now need to setup `git review` to communicate with review.gluster.org. -First, determine your `git review` setup by typing: +### Some additional git configs +These are the changes you need to make to the git configuration so you can download and verify someone's work. +Open your .git/config file in your editor and locate the section for your GitHub remote. It should look something like this: ~~~ -git review -s +[remote "upstream"] + url = git@github.com:/swiftonfile.git + fetch = +refs/heads/*:refs/remotes/upstream/* ~~~ - -If there is no output, then everything is setup correctly. If the output -contains the string *We don't know where your gerrit is*, then you need to -setup a remote repo with the name `gerrit`. You can inspect the current -remote repo's by typing the following command. - +We're going to add a new refspec to this section so that it now looks like this: ~~~ -git remote -v -~~~ - -To add the Gerrit remote repo, type the following: - -~~~ -git remote add gerrit ssh://@review.gluster.org/gluster-swift -git remote -v -~~~ - -Now we can confirm that `git review` has been setup by typing the -following and noticing no output is returned: - -~~~ -git review -s +[remote "upstream"] + url = git@github.com:/swiftonfile.git + fetch = +refs/heads/*:refs/remotes/upstream/* + fetch = +refs/pull/*/head:refs/pull/upstream/* ~~~ ### Tox and Nose -Like OpenStack Swift, Gluster for Swift uses `tox` python virtual +Like OpenStack Swift, SwiftOnFile uses `tox` python virtual environment for its unit tests. To install `tox` type: ~~~ @@ -148,8 +123,8 @@ tests are available under the `test/unit` directory. To run the functional tests, the following requirements must be met. 1. `/etc/swift` must not exist. -1. User needs to have `sudo` access -1. `/mnt/gluster-object/test` and `/mnt/gluster-object/test2` directories +2. User needs to have `sudo` access +3. `/mnt/gluster-object/test` and `/mnt/gluster-object/test2` directories must be created on either an XFS or GlusterFS volume. Once the requirements have been met, you can now run the full functional @@ -181,44 +156,60 @@ contains less than 70 characters. For more information on commit messages, please visit the [Git Commit Messages][] page in OpenStack.org. -### Uploading to Gerrit -Once you have the changes ready for review, you can submit it to Gerrit +### Uploading changes to Your Fork +Once you have the changes ready for review, you can submit it to your github fork topic branch. by typing: ~~~ -git review +git push origin TOPIC-BRANCH ~~~ +### Creating Pull request +You pushed a commit to a topic branch in your fork, and would like someone to review and merge. + +Navigate to your repository with the changes you want someone else to pull and press the Pull Request button. + +Branch selection ==> Switch to your branch + +Pull Request ==> Click the Compare & review button + +Pull requests can be sent from any branch or commit but it's recommended that a topic branch be used so that follow-up commits can be pushed to update the pull request if necessary. + +### Reviewing the pull request +After starting the review, you're presented with a review page where you can get a high-level overview of what exactly has changed between your branch and the repository's master branch. You can review all comments made on commits, identify which files changed, and get a list of contributors to your branch. + After the change is reviewed, you might have to make some -additional modifications to your change. To continue the work for -a specific change, you can query Gerrit for the change number by -typing: +additional modifications to your change.You just need to do changes to your local topic branch, commit it, and push it to same branch on your github fork repo. If the branch is currently being used for a pull request, then the branch changes are automatically tracked by the pull request. +If 'all goes well' your change will be merged to project swiftonfile. What 'all goes well' means, is this: + +1. Travis-CI passes unit-tests. +2. Jenkins passes functional-tests. +3. It got +1 by at least 2 reviewers. +4. A core-reviewer can give this pull request a +2 and merge it to the project repo. + +### Download and Verify someone's pull request +You can fetch all the pull requests using: ~~~ -git review -l +git fetch origin +# From github.com:swiftonfile/swiftonfile +# * [new ref] refs/pull/1000/head -> refs/pull/origin/1000 +# * [new ref] refs/pull/1002/head -> refs/pull/origin/1002 +# * [new ref] refs/pull/1004/head -> refs/pull/origin/1004 +# * [new ref] refs/pull/1009/head -> refs/pull/origin/1009 ~~~ -Then download the change to make the new modifications by typing: - +You should now be able to check out a pull request in your local repository as follows: ~~~ -git review -d CHANGE_NUMBER +git checkout -b 999 pull/origin/999 +# Switched to a new branch '999' ~~~ -where CHANGE_NUMBER is the Gerrit change number. - -If you need to create a new patch for a change and include your update(s) -to your last commit type: - +To test this changes you can prepare tox virtual env to run with the change using: ~~~ -git commit -as --amend -~~~ - -Now that you have finished updating your change, you need to re-upload -to Gerrit using the following command: - -~~~ -git review +#tox -e run ~~~ +If all the prerequisite for running tox are there you should be able to see the bash prompt, where you can test these changes. ## Creating Distribution Packages @@ -233,13 +224,10 @@ of the RPM: `$ PKG_RELEASE=123 bash makerpm.sh` - -[OpenStack Gerrit Workflow]: https://wiki.openstack.org/wiki/Gerrit_Workflow -[Gerrit]: https://code.google.com/p/gerrit/ -[review.gluster.org]: http://review.gluster.org -[SSH Key]: http://review.gluster.org/#/settings/ssh-keys +[swiftonfile repo]: https://github.com/swiftonfile/swiftonfile [GitHub Generating SSH Keys]: https://help.github.com/articles/generating-ssh-keys [PEP8]: http://www.python.org/dev/peps/pep-0008 [Git Commit Messages]: https://wiki.openstack.org/wiki/GitCommitMessages [GlusterFS Compiling RPMS]: https://forge.gluster.org/glusterfs-core/pages/CompilingRPMS [README]: http://repos.fedorapeople.org/repos/openstack/openstack-trunk/README + From 9f4b8c838f2dcd4a3430e9b1947bc8668ed816df Mon Sep 17 00:00:00 2001 From: Pushpesh Sharma Date: Tue, 6 May 2014 15:19:40 +0530 Subject: [PATCH 2/8] Minor Update --- doc/markdown/dev_guide.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/markdown/dev_guide.md b/doc/markdown/dev_guide.md index 36942f7..714910b 100644 --- a/doc/markdown/dev_guide.md +++ b/doc/markdown/dev_guide.md @@ -5,7 +5,7 @@ The workflow for SwiftOnFile is largely based upon the Github WorkFlow. ### Account Setup -You can create a free account on github.It would be better to create keys and add your public key to github, else you can provide username/password each time you communicate with github from any remote machine.Follow the the information given at [GitHub Generating SSH Keys][] if you need help creating your key.You have to create a fork of [swiftonfile repo][] for your development work.You can create your fork from the github Web UI. +You can create a free account on github. It would be better to create keys and add your public key to github, else you can provide username/password each time you communicate with github from any remote machine. Follow the the information given at [GitHub Generating SSH Keys][] if you need help creating your key. You have to create a fork of [swiftonfile repo][] for your development work. You can create your fork from the github Web UI. ### Package Requirements Type the following to install the required packages: @@ -165,9 +165,9 @@ git push origin TOPIC-BRANCH ~~~ ### Creating Pull request -You pushed a commit to a topic branch in your fork, and would like someone to review and merge. +You pushed a commit to a topic branch in your fork, and now you would like it to be merge in the swiftonfile project. -Navigate to your repository with the changes you want someone else to pull and press the Pull Request button. +Navigate to your forked repo, locate the change your would like to be merged to swiftonfile and click on the Pull Request button. Branch selection ==> Switch to your branch @@ -191,17 +191,17 @@ If 'all goes well' your change will be merged to project swiftonfile. What 'all ### Download and Verify someone's pull request You can fetch all the pull requests using: ~~~ -git fetch origin +git fetch upstream # From github.com:swiftonfile/swiftonfile -# * [new ref] refs/pull/1000/head -> refs/pull/origin/1000 -# * [new ref] refs/pull/1002/head -> refs/pull/origin/1002 -# * [new ref] refs/pull/1004/head -> refs/pull/origin/1004 -# * [new ref] refs/pull/1009/head -> refs/pull/origin/1009 +# * [new ref] refs/pull/1000/head -> refs/pull/upstream/1000 +# * [new ref] refs/pull/1002/head -> refs/pull/upstream/1002 +# * [new ref] refs/pull/1004/head -> refs/pull/upstream/1004 +# * [new ref] refs/pull/1009/head -> refs/pull/upstream/1009 ~~~ You should now be able to check out a pull request in your local repository as follows: ~~~ -git checkout -b 999 pull/origin/999 +git checkout -b 999 pull/upstream/999 # Switched to a new branch '999' ~~~ From f5a5b84b00b690b2832a9ad5dd80fda40fe0ca45 Mon Sep 17 00:00:00 2001 From: Pushpesh Sharma Date: Tue, 27 May 2014 14:52:18 +0530 Subject: [PATCH 3/8] Minor update --- doc/markdown/dev_guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/markdown/dev_guide.md b/doc/markdown/dev_guide.md index 714910b..5b0240a 100644 --- a/doc/markdown/dev_guide.md +++ b/doc/markdown/dev_guide.md @@ -149,8 +149,8 @@ characters. 3. A line, or multiple line description of the change where each line contains less than 70 characters. 4. Blank line -5. If this is a bug fix, then it should have a line as follows: -`BUG 12345: ` +5. If this is a bug/issue fix, then it should have a line as follows: +`Issue #` 6. Blank line. For more information on commit messages, please visit the From 6373686f368695ab7fc106949a8e535a516012c1 Mon Sep 17 00:00:00 2001 From: Pushpesh Sharma Date: Tue, 27 May 2014 15:24:55 +0530 Subject: [PATCH 4/8] Minor update --- doc/markdown/dev_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/markdown/dev_guide.md b/doc/markdown/dev_guide.md index 5b0240a..25fa8ca 100644 --- a/doc/markdown/dev_guide.md +++ b/doc/markdown/dev_guide.md @@ -138,7 +138,7 @@ tox -e functest After making the changes needed, you can commit your changes by typing: ~~~ -git commit -as +git commit -a ~~~ where the commit message should follow the following recommendations: From 9619f54d6e41da9ba90eb43a58237bdab96b2fa0 Mon Sep 17 00:00:00 2001 From: Pushpesh Sharma Date: Wed, 28 May 2014 10:24:34 +0530 Subject: [PATCH 5/8] Including Thiago's suggestions --- doc/markdown/dev_guide.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/doc/markdown/dev_guide.md b/doc/markdown/dev_guide.md index 25fa8ca..f301e81 100644 --- a/doc/markdown/dev_guide.md +++ b/doc/markdown/dev_guide.md @@ -34,19 +34,19 @@ git config --global user.email "your_email@youremail.com" ~~~ ### Clone your fork -You can clone the fork you created using github Web UI.By convention it will be called 'origin'. +You can clone the fork you created using github Web UI. By convention it will be called 'origin'. ~~~ git clone git@github.com:/swiftonfile.git cd swiftonfile ~~~ ### Add upstream repo -You can add swiftonfile project repo, to get the latest updates from the project.It will be called upstream by convention. +You can add swiftonfile project repo, to get the latest updates from the project. It will be called upstream by convention. ~~~ git remote add upstream git@github.com:swiftonfile/swiftonfile.git ~~~ -You can confirm these setting using 'git remote -v' it should give you somthing like this: +You can confirm these setting using 'git remote -v' it should give you something like this: ~~~ origin git@github.com:/swiftonfile.git (fetch) origin git@github.com:/swiftonfile.git (push) @@ -149,9 +149,12 @@ characters. 3. A line, or multiple line description of the change where each line contains less than 70 characters. 4. Blank line -5. If this is a bug/issue fix, then it should have a line as follows: +5. If this is a bug fix or enhancement, then it should have a line as follows: `Issue #` -6. Blank line. +6. It may contain any external URL references like a launchpad blueprint. +7. Blank line. + +>Note: A bug or an enhancement both can be loged in github as an issue. For more information on commit messages, please visit the [Git Commit Messages][] page in OpenStack.org. @@ -179,7 +182,7 @@ Pull requests can be sent from any branch or commit but it's recommended that a After starting the review, you're presented with a review page where you can get a high-level overview of what exactly has changed between your branch and the repository's master branch. You can review all comments made on commits, identify which files changed, and get a list of contributors to your branch. After the change is reviewed, you might have to make some -additional modifications to your change.You just need to do changes to your local topic branch, commit it, and push it to same branch on your github fork repo. If the branch is currently being used for a pull request, then the branch changes are automatically tracked by the pull request. +additional modifications to your change. You just need to do changes to your local topic branch, commit it, and push it to same branch on your github fork repo. If the branch is currently being used for a pull request, then the branch changes are automatically tracked by the pull request. If 'all goes well' your change will be merged to project swiftonfile. What 'all goes well' means, is this: From f2302af6767653d00b75ac185c643ca9e269c6d9 Mon Sep 17 00:00:00 2001 From: Pushpesh Sharma Date: Wed, 28 May 2014 10:32:29 +0530 Subject: [PATCH 6/8] Minor Update --- doc/markdown/dev_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/markdown/dev_guide.md b/doc/markdown/dev_guide.md index f301e81..d238cbc 100644 --- a/doc/markdown/dev_guide.md +++ b/doc/markdown/dev_guide.md @@ -154,7 +154,7 @@ contains less than 70 characters. 6. It may contain any external URL references like a launchpad blueprint. 7. Blank line. ->Note: A bug or an enhancement both can be loged in github as an issue. +> Note: A bug or an enhancement both can be loged in github as an issue. For more information on commit messages, please visit the [Git Commit Messages][] page in OpenStack.org. From 21708ef03c6b8aa3272c3e13d2e47bba2640a95a Mon Sep 17 00:00:00 2001 From: Pushpesh Sharma Date: Wed, 28 May 2014 14:50:39 +0530 Subject: [PATCH 7/8] Including Prashant's suggestions --- doc/markdown/dev_guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/markdown/dev_guide.md b/doc/markdown/dev_guide.md index d238cbc..afad167 100644 --- a/doc/markdown/dev_guide.md +++ b/doc/markdown/dev_guide.md @@ -168,9 +168,9 @@ git push origin TOPIC-BRANCH ~~~ ### Creating Pull request -You pushed a commit to a topic branch in your fork, and now you would like it to be merge in the swiftonfile project. +You pushed a commit to a topic branch in your fork, and now you would like it to be merged in the swiftonfile project. -Navigate to your forked repo, locate the change your would like to be merged to swiftonfile and click on the Pull Request button. +Navigate to your forked repo, locate the change you would like to be merged to swiftonfile and click on the Pull Request button. Branch selection ==> Switch to your branch From a60098a2ab3de96633c4cb9ba4a2989a074a04f4 Mon Sep 17 00:00:00 2001 From: Pushpesh Sharma Date: Wed, 28 May 2014 17:04:25 +0530 Subject: [PATCH 8/8] Minor update --- doc/markdown/dev_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/markdown/dev_guide.md b/doc/markdown/dev_guide.md index afad167..4b311de 100644 --- a/doc/markdown/dev_guide.md +++ b/doc/markdown/dev_guide.md @@ -138,7 +138,7 @@ tox -e functest After making the changes needed, you can commit your changes by typing: ~~~ -git commit -a +git commit -as ~~~ where the commit message should follow the following recommendations: