diff --git a/README b/README deleted file mode 100644 index 5f7df7a..0000000 --- a/README +++ /dev/null @@ -1,28 +0,0 @@ -Gluster For Swift - Integrating GlusterFS with OpenStack Swift Implementation -of the Swift API. This is a component of the Unified File and Object (UFO) -story for GlusterFS, which allows files and directories created via -gluster-native/nfs/samba mount(s) to be accessed as accounts, containers and -objects. - -Install - * yum install openstack-swift*.noarch - * yum install gluster-swift-1.3*.noarch - -Once this is done, you can access GlusterFS volumes via the Swift API where -accounts are mounted volumes (today), containers are top-level directories, -and objects are files and sub-directories of container directories. - -Command to start the servers (TBD) - swift-init main start - -Command to stop the servers (TBD) - swift-init main stop - -Command to gracefully reload the servers - swift-init main reload - -Building RPMs. RPMs will be located in the 'build' directory. - $ bash makerpm.sh - -Building RPM with a specific release value, useful for automatic Jenkin builds - $ PROG_RELEASE=123 bash makerpm.sh diff --git a/README.md b/README.md new file mode 100644 index 0000000..236bbd7 --- /dev/null +++ b/README.md @@ -0,0 +1,12 @@ +# Gluster For Swift +Integrating GlusterFS as the back-end to OpenStack Swift +implementation. This is a component of the Unified File and Object (UFO) +story for GlusterFS, which allows files and directories created via +gluster-native/nfs/samba mount(s) to be accessed as objects via +the Swift API. + +# Table of Contents +1. [Overview and Concepts](doc/markdown/concepts.md) +1. [Usage Guide](doc/markdown/user_guide.md) +1. [Developer Guide](doc/markdown/dev_guide.md) + diff --git a/doc/markdown/concepts.md b/doc/markdown/concepts.md new file mode 100644 index 0000000..2ad3f25 --- /dev/null +++ b/doc/markdown/concepts.md @@ -0,0 +1,2 @@ +# Overview and Concepts +TBD diff --git a/doc/markdown/dev_guide.md b/doc/markdown/dev_guide.md new file mode 100644 index 0000000..c2f5b68 --- /dev/null +++ b/doc/markdown/dev_guide.md @@ -0,0 +1,186 @@ +# Developer Guide + +## Contributing to the project + +## Development Environment Setup +The workflow for Gluster-Swift is largely based upon the +[OpenStack Gerrit 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. + +### Download the source +The source for Gluster for Swift is available in Github. To download +type: + +~~~ +git clone https://github.com/gluster/gluster-swift.git +cd gluster-swift +~~~ + +### Git Review +The tool `git review` is a simple tool to automate interaction with Gerrit. +We recommend using this tool to upload, modify, and query changes in Gerrit. +The tool can be installed by running the following command: + +~~~ +pip install git-review +~~~ + +Note that while many distros offer a version of `git review`, they don't +necessarily keep it up to date. Pip gives one the latest which +often avoids problems with various Gerrit servers. + +We now need to setup `git review` to communicate with review.gluster.org. +First, let's determine our `git review` setup by typing: + +~~~ +git review -s +~~~ + +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 we need +a setup a remote repo with the name `gerrit`. We can inspect the current +remote repo's by typing the following command. + +~~~ +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 +~~~ + +### Tox and Nose +Like OpenStack Swift, Gluster for Swift uses `tox` python virtual +environment for its unit tests. To install `tox` type: + +~~~ +pip install tox nose +~~~ + +## Workflow + +### Create a topic branch +It is recommended to create a branch in git when working on a specific topic. +If you are currently on the *master* branch, you can type the following +to create a topic branch: + +~~~ +git checkout -b TOPIC-BRANCH +~~~ + +where *TOPIC-BRANCH* is either bug/bug-number (e.g. bug/123456) or +a meaningful name for the topic (e.g. feature_xyz) + +### Quality Checking +#### PEP8 +To test that the code adheres to the [PEP8][] specification, please +type: + +~~~ +tox -e pep8 +~~~ + +#### Unit Tests +You can run the unit tests after making your changes. To run the unit +test suite in `tox` type the following as a non-root user: + +~~~ +tox -e ENV +~~~ + +where *ENV* is either `py27` for systems with Python 2.7+, or `py26` for +systems with Python 2.6+. + +#### Functional Tests +Fuctional tests are used to test a running Gluster for Swift environment. +**TBD**. + +### Commiting changes +After making the changes needed, you can commit your changes by typing: + +~~~ +git commit -as +~~~ + +where the commit message should follow the following recommendations: + +1. The first line should be a brief message and contain less than 50 +characters. +2. Second line blank +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: ` +6. Blank line. + +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 +simply by typing: + +~~~ +git review +~~~ + +After the change is reviewed, most likely you may 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: + +~~~ +git review -l +~~~ + +Then download the change to make the new modifications by typing: + +~~~ +git review -d CHANGE_NUMBER +~~~ + +where CHANGE_NUMBER is the Gerrit change number. + +## Creating Distribution Packages + +### Tools Installation +TBD: For now please follow the installation instructions +on the [GlusterFS Compiling RPMS][] page. + +### Building RPMs for Fedora/RHEL/CentOS Systems +Building RPMs. RPMs will be located in the *build* directory. + +`$ bash makerpm.sh` + +Building RPM with a specific release value, useful for automatic +Jenkin builds, or keeping track of different versions 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 +[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 diff --git a/doc/markdown/user_guide.md b/doc/markdown/user_guide.md new file mode 100644 index 0000000..6108832 --- /dev/null +++ b/doc/markdown/user_guide.md @@ -0,0 +1,66 @@ +# User Guide + +## Installation + +### GlusterFS Installation +First, we need to install GlusterFS on the system by following the +instructions on [GlusterFS QuickStart Guide][]. + +### Fedora/RHEL/CentOS +Gluster for Swift depends on OpenStack Swift Grizzly, which can be +obtained by using [RedHat's RDO][] packages as follows: + +~~~ +yum install -y http://rdo.fedorapeople.org/openstack/openstack-grizzly/rdo-release-grizzly.rpm +~~~ + +### Download +Gluster for Swift uses [Jenkins][] for continuous integration and +creation of distribution builds. Download the latest RPM builds +from one of the links below: + +* RHEL/CentOS 6: [Download](http://build.gluster.org/job/gluster-swift-builds-cent6/lastSuccessfulBuild/artifact/build/) +* Fedora 18+: [Download](http://build.gluster.org/job/gluster-swift-builds-f18/lastSuccessfulBuild/artifact/build/) + +Install the downloaded RPM using the following command: + +~~~ +yum install -y RPMFILE +~~~ + +where *RPMFILE* is the RPM file downloaded from Jenkins. + +## Configuration +TBD + +## Server Control +Command to start the servers (TBD) + +~~~ +swift-init main start +~~~ + +Command to stop the servers (TBD) + +~~~ +swift-init main stop +~~~ + +Command to gracefully reload the servers + +~~~ +swift-init main reload +~~~ + +### Mounting your volumes +TBD + +Once this is done, you can access GlusterFS volumes via the Swift API where +accounts are mounted volumes, containers are top-level directories, +and objects are files and sub-directories of container directories. + + + +[GlusterFS QuickStart Guide]: http://www.gluster.org/community/documentation/index.php/QuickStart +[RedHat's RDO]: http://openstack.redhat.com/Quickstart +[Jenkins]: http://jenkins-ci.org