x/swiftonhpss
Code Issues Proposed changes

Update dev_guide.md

Browse Source
This commit is contained in:
Thiago da Silva 2014-07-31 13:13:00 -04:00
parent c70faa4e27
commit 12c675ab27
1 changed files with 31 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
doc/markdown/dev_guide.md
View File

@ -2,10 +2,10 @@
## Development Environment Setup ## Development Environment Setup
The workflow for SwiftOnFile is largely based upon the The workflow for SwiftOnFile is largely based upon the
Github WorkFlow. [GitHub work flow][] using the [fork and pull model][].
### Account Setup ### 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 ### Package Requirements
Type the following to install the required packages: Type the following to install the required packages:
@ -34,9 +34,9 @@ git config --global user.email "your_email@youremail.com"
~~~ ~~~
### Clone your fork ### 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:<username>/swiftonfile.git git clone git@github.com:<your_username>/swiftonfile.git
cd swiftonfile cd swiftonfile
~~~ ~~~
@ -46,31 +46,48 @@ You can add swiftonfile project repo, to get the latest updates from the project
git remote add upstream git@github.com:swiftonfile/swiftonfile.git git remote add upstream git@github.com:swiftonfile/swiftonfile.git
~~~ ~~~
You can confirm these setting using 'git remote -v' it should give you something like this: You can confirm these setting using 'git remote -v'. It should give you something like this:
~~~ ~~~
origin git@github.com:<username>/swiftonfile.git (fetch) origin git@github.com:<your_username>/swiftonfile.git (fetch)
origin git@github.com:<username>/swiftonfile.git (push) origin git@github.com:<your_username>/swiftonfile.git (push)
upstream git@github.com:swiftonfile/swiftonfile.git (fetch) upstream git@github.com:swiftonfile/swiftonfile.git (fetch)
upstream git@github.com:swiftonfile/swiftonfile.git (push) upstream git@github.com:swiftonfile/swiftonfile.git (push)
~~~ ~~~
### Some additional git configs ### Code reviews
These are the changes you need to make to the git configuration so you can download and verify someone's work. 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: Open your .git/config file in your editor and locate the section for your GitHub remote. It should look something like this:
~~~ ~~~
[remote "upstream"] [remote "upstream"]
url = git@github.com:<USERNAME>/swiftonfile.git url = git@github.com:<your_username>/swiftonfile.git
fetch = +refs/heads/*:refs/remotes/upstream/* fetch = +refs/heads/*:refs/remotes/upstream/*
~~~ ~~~
We're going to add a new refspec to this section so that it now looks like this: We're going to add a new refspec to this section so that it now looks like this:
~~~ ~~~
[remote "upstream"] [remote "upstream"]
url = git@github.com:<USERNAME>/swiftonfile.git url = git@github.com:<your_username>/swiftonfile.git
fetch = +refs/heads/*:refs/remotes/upstream/* fetch = +refs/heads/*:refs/remotes/upstream/*
fetch = +refs/pull/*/head:refs/pull/upstream/* fetch = +refs/pull/*/head:refs/pull/upstream/*
~~~ ~~~
#### Download and Verify someone's pull request
You can fetch all the pull requests using:
~~~
git fetch upstream
# From github.com:swiftonfile/swiftonfile
# * [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/upstream/999
# Switched to a new branch '999'
~~~
### Tox and Nose ### Tox and Nose
Like OpenStack Swift, SwiftOnFile uses `tox` python virtual Like OpenStack Swift, SwiftOnFile uses `tox` python virtual
environment for its unit tests. To install `tox` type: environment for its unit tests. To install `tox` type:
@ -120,15 +137,7 @@ tests are available under the `test/unit` directory.
#### Functional Tests #### Functional Tests
##### Executing the tests ##### Executing the tests
To run the functional tests, the following requirements must be met. To run the functional tests, run the command:
1. `/etc/swift` must not exist.
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
tests using the following command:
~~~ ~~~
tox -e functest tox -e functest
@ -170,7 +179,7 @@ git push origin TOPIC-BRANCH
### Creating Pull request ### Creating Pull request
You pushed a commit to a topic branch in your fork, and now you would like it to be merged 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 you would like to be merged to swiftonfile and click on the Pull Request button. Navigate to your forked repo, locate the branch you would like to be merged to swiftonfile and click on the Pull Request button.
Branch selection ==> Switch to your branch Branch selection ==> Switch to your branch
@ -191,28 +200,6 @@ If 'all goes well' your change will be merged to project swiftonfile. What 'all
3. It got +1 by at least 2 reviewers. 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. 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 fetch upstream
# From github.com:swiftonfile/swiftonfile
# * [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/upstream/999
# Switched to a new branch '999'
~~~
To test this changes you can prepare tox virtual env to run with the change using:
~~~
#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 ## Creating Distribution Packages
@ -227,6 +214,8 @@ of the RPM:
`$ PKG_RELEASE=123 bash makerpm.sh` `$ PKG_RELEASE=123 bash makerpm.sh`
[GitHub work flow]: https://guides.github.com/introduction/flow/index.html
[fork and pull model]: https://help.github.com/articles/using-pull-requests
[swiftonfile repo]: https://github.com/swiftonfile/swiftonfile [swiftonfile repo]: https://github.com/swiftonfile/swiftonfile
[GitHub Generating SSH Keys]: https://help.github.com/articles/generating-ssh-keys [GitHub Generating SSH Keys]: https://help.github.com/articles/generating-ssh-keys
[PEP8]: http://www.python.org/dev/peps/pep-0008 [PEP8]: http://www.python.org/dev/peps/pep-0008