summaryrefslogtreecommitdiffstats
path: root/doc/markdown
diff options
context:
space:
mode:
Diffstat (limited to 'doc/markdown')
-rw-r--r--doc/markdown/concepts.md2
-rw-r--r--doc/markdown/dev_guide.md186
-rw-r--r--doc/markdown/user_guide.md66
3 files changed, 254 insertions, 0 deletions
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://<username>@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: <url to bug>`
+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