Merge pull request #1057 from sushimustwrite/master

Documentation updates

documentation/contribute/Readme.markdown

@@ -7,7 +7,7 @@ Alright, we get it. You'd rather code than read. Here's the checklist.
 1. Fork the <a href="https://github.com/photo/frontend">frontend</a> repository. <a href="http://help.github.com/fork-a-repo/">More info on forking</a>.
 1. Follow one of our <a href="/documentation">guides</a> on setting the software up.
 1. Get coding!
-1. <a href="/contribute/frontend">More details</a> if you need.
+1. <a href="/contribute/frontend">More details</a> if you need them.
 
 <div></div>
 
@@ -24,17 +24,17 @@ Alright, we get it. You'd rather code than read. Here's the checklist.
     # as a result it maybe unstable so you can always use master which should work
     user@[frontend] git checkout development
 
-    # make your changes and commit then locally
+    # make your changes and commit them locally
     user@[frontend] git commit -m 'Lots of details! Closes #123'
     user@[frontend] git push origin development
 
 Now you're ready to <a href="http://help.github.com/send-pull-requests/">send a pull request</a>!
 
 ## There's a spot for everyone to be a part of something BIG
 
-Hear ye, hear ye! <a href="#developers">Developers</a>, <a href="designers">designers</a>, <a href="#copywriters">copywriters</a>, <a href="#community">community managers</a>, <a href="#translators">translators</a>, and anyone else who wants to help. If you want to contribute to The OpenPhoto Project, the good news is that there's probably a place where we could use your help!
+Hear ye, hear ye! <a href="#developers">Developers</a>, <a href="#designers">designers</a>, <a name="#powerusers">power users</a>, <a href="#copywriters">copywriters</a>, <a href="#community">community managers</a>, <a href="#translators">translators</a>, and anyone else who wants to help. If you want to contribute to The OpenPhoto Project, the good news is that there's probably a place where we could use your help!
 
-It's easy to get in touch with us, as many of us hang out in #openphoto on Freenode. Don't hesitate to come and <a href="http://webchat.freenode.net/">chat with us</a>. We're happy to answer any questions you might have.
+It's easy to get in touch with us, as many of us hang out in #openphoto on Freenode. Come in and <a href="http://webchat.freenode.net/">chat with us</a>. We're happy to answer any questions you might have.
 
 Here's a full list of ways to contact us:
 
@@ -65,16 +65,20 @@ That being said, the largest part of the code base is the <a href="https://githu
 
 If you've got a gift with words we're in desperate need of your help. Much of the community consists of engineers and well, we suck at taking complex ideas and distilling them into small and easy to understand sentences.
 
-The best way to get started is to read the copy at the <a href="http://theopenphotoproject.org">The OpenPhoto Project</a> website. Some of it is technical, like the documentation, but much of it is also trying to explain  why users should care about what we're building. Wherever your passion lies, we will definitely appreciate the help.
+The best way to get started is to read the copy at <a href="http://theopenphotoproject.org">The OpenPhoto Project</a>'s website. Some of it is technical, like the documentation, but much of it is also trying to explain why users should care about what we're building. Wherever your passion lies, we will definitely appreciate the help.
 
 Everything can be found in the <a href="https://github.com/photo/community">community</a> repository for the non-technical bits or the <a href="https://github.com/photo/frontend">frontend</a> repository for the documentation.
 
-You can open an issue for the appropriate repository or fork it and send us a pull request. If you have any questions, let us know using one of the channels above.
+We have <a href="https://github.com/photo/frontend/issues?labels=Documentation&page=1&state=open">issues tagged documentation</a> on Github, but just about every area of the site needs some attention. You can open an issue for the appropriate repository or fork it and send us a pull request. If you have any questions, let us know using one of the channels above.
+
+<a name="powerusers"></a>
+## Power Users
+Do you know OpenPhoto inside out, including all its little quirks? Then we need you! A lot of people ask questions about OpenPhoto on our mailing list or on IRC, so hang out on those channels and help someone out. This is a great way to get to know other OpenPhoto users. You can also help out by filing Github issues when you find bugs and discussing them on our issues board.
 
 <a name="community"></a>
 ## Community Managers and Social Media
 
-Send an email to <a href="mailto:hello@openphoto.me">hello@openphoto.me</a> or <a href="https://twitter.com/photo">@mention us</a> on Twitter if you'd like to help with Community Management or Social Media.
+Send an email to <a href="mailto:hello@openphoto.me">hello@openphoto.me</a> or <a href="https://twitter.com/openphoto">@mention us</a> on Twitter if you'd like to help with Community Management or Social Media.
 
 <a name="translators"></a>
 ## Translators

documentation/contribute/frontend.markdown

@@ -3,7 +3,7 @@ Contributing to the Web and API components
 
 ## Up and contributing in under 5 minutes
 
-So what do you need to start contributing?
+So what do you need to get started?
 
 A computer! Once you've secured one of those all you need is a Github account. It helps to have a locally installed version of the frontend repository to test your changes. We've got <a href="http://theopenphotoproject.org/documentation">lots of guides</a> to help you get started. If you're updating any of the PHP code you should get PHPUnit as well.
 
@@ -16,12 +16,14 @@ A computer! Once you've secured one of those all you need is a Github account. I
     # http://www.phpunit.de/manual/3.6/en/installation.html
     # http://stackoverflow.com/questions/3301300/setting-up-phpunit-on-osx
 
-Now that you've got the following we can continue.
+Now that you've got:
 
 * A computer
 * <a href="https://github.com">A GitHub account</a>
 * An <a href="http://theopenphotoproject.org/documentation">installation of the frontend repository</a>
-* <a href="http://www.phpunit.de/manual/3.6/en/installation.html">PHPUnit</a>
+* <a href="http://www.phpunit.de/manual/3.6/en/installation.html">PHPUnit</a>,
+
+let's continue.
 
 ## Deciding what to fix
 
@@ -32,6 +34,27 @@ We've added a _Beginner_ label to issues that don't touch some of the more sensi
 * <a href="https://github.com/photo/frontend/issues?labels=Beginner%2CJavaScript&sort=created&direction=desc&state=open&page=1">Beginner + JavaScript issues</a>
 * <a href="https://github.com/photo/frontend/issues?labels=Beginner%2CPHP&sort=created&direction=desc&state=open&page=1">Beginner + PHP issues</a>
 
+## Things to keep in mind while you code
+Here's what your code should adhere to:
+
+* Unit tests should pass (more on that in the next section)
+* Spacing matters: two spaces, no tabs
+* Commits should reference an issue number (more on that below)
+* Comment your code so future developers can tell what's going on
+* Curly braces go on their own line. For example:
+````php
+  if(condition)
+  {
+      statement 1;
+      statement 2;
+  }
+
+  // or
+  if(condition)
+      only statement;
+````
+All in all, we recognize that everyone has a different style and level of experience, and we welcome all pull requests.
+
 ## Testing that your change didn't break anything
 
 Once you've made your change and verified it does what it should it's time to make sure it's not doing something it shouldn't. This is as easy as a single command.
@@ -49,14 +72,14 @@ Once you've made your change and verified it does what it should it's time to ma
     OK, but incomplete or skipped tests!
     Tests: 311, Assertions: 661, Incomplete: 4.
 
-Those `I`s are okay but you shouldn't see any `E`s or `F`s and definitely look for the _OK_ message at the end. If all the tests pass then you're good to go and can commit it.
+Those `I`s are okay but you shouldn't see any `E`s or `F`s and definitely look for the `OK` message at the end. If all the tests pass then you're good to go and can commit your changes.
 
-You can also automate this by adding a pre-commit hook. Just copy <a href="https://github.com/photo/frontend/blob/master/documentation/hooks/pre-commit">this file</a> into your `.git/hooks` directory or run the command below.
+You can automate this by adding a pre-commit hook. Just copy <a href="https://github.com/photo/frontend/blob/master/documentation/hooks/pre-commit">this file</a> into your `.git/hooks` directory or run the command below.
 
     wget --no-check-certificate https://raw.github.com/photo/frontend/master/documentation/hooks/pre-commit -O .git/hooks/pre-commit
     chmod u+x .git/hooks/pre-commit
 
-Now everytime you make a commit it will first run the unit tests, automatically.
+Now every time you make a commit it will first run the unit tests automatically.
 
 ## Committing your code
 
@@ -74,9 +97,9 @@ Be descriptive, it helps a ton. Once you've committed your code it's time to pus
 
 ## Getting your change into the OpenPhoto branch
 
-To get your change merged into the official OpenPhoto branch you should submit a pull request. <a href="http://help.github.com/send-pull-requests/"GitHub's tutorial</a> is better than anything we could do so we'll link to it.
+To get your change merged into the official OpenPhoto branch, submit a pull request. <a href="http://help.github.com/send-pull-requests/">GitHub's tutorial</a> is better than anything we could do so we'll link to it.
 
-It makes everyone's life easier if you can remember to issue the pull request to OpenPhoto's development. If you forget, no big deal. The important thing is we get your change and your awesomeness can be merged into everyone else's awesomeness.
+It makes everyone's lives easier if you can remember to issue the pull request to OpenPhoto's development branch. If you forget, no big deal. The important thing is we get your change and your awesomeness can be merged into everyone else's awesomeness.
 
 ## Help! I'm stuck and have questions
 

documentation/faq/SelfHostedFaq.markdown

@@ -0,0 +1,21 @@
+## Self-Hosted OpenPhoto FAQ
+### How can I install OpenPhoto?
+We have lots of guides to help you through the installation process. <a href="http://theopenphotoproject.org/documentation">Check them out here</a>. We welcome <a href="http://github.com/photo/frontend">contributions on Github</a> if you see one that's incomplete.
+
+### Can I install OpenPhoto to a subdirectory of my site?
+Not yet, but it's on our wishlist.
+
+### How does support for multiple users work?
+We support multiple users through separate domains. <a href="https://github.com/photo/frontend/issues/318">See this issue on why it works that way.</a>
+
+### Is your mobile app available for self-hosted users?
+Yes! Download the app <a href="http://itunes.com/apps/theopenphotoapp">for iOS</a> or <a href="https://play.google.com/store/apps/details?id=me.openphoto.android.app">Android</a>.
+
+### I just changed my domain name. Why am I getting prompted for new settings?
+This is normal. OpenPhoto configs are bound to a site, not a server. Since a site is defined by its hostname, you can have multiple sites on one host provided that they have different hostnames. So go ahead and change your settings.
+
+### I encountered a security issue in OpenPhoto. What's the best way to let you know?
+<a href="https://github.com/photo/frontend/issues">Report it as an issue at Github</a>. If you don't feel comfortable exposing a security issue, reach out to someone on the core team and email us individually.
+
+### Something broke. How do I let you know?
+Check <a href="https://github.com/photo/frontend/issues">our issue tracker at Github</a> first; if the issue you're encountering isn't already there, then start a new issue and describe what you ran across.

documentation/guides/InstallationSharedHosting.markdown

@@ -0,0 +1,131 @@
+# OpenPhoto / Installation for Shared Hosting
+
+#### OpenPhoto, a photo service for the masses
+
+## Installation on Shared Hosting
+
+This guide instructs you on how to install OpenPhoto on shared hosting sites such as Dreamhost or Bluehost. OpenPhoto can be difficult to install for users not experienced with performing such installations. If you'd like to use OpenPhoto without installing the software yourself, <a href="http://openphoto.me">get started here</a>.
+
+If you're using Dreamhost <a href="https://github.com/photo/frontend/blob/master/documentation/guides/InstallationDreamhost.markdown">we have a community-written guide for Dreamhost users</a>. Because every webhost is unique, we welcome additions to this guide as well as guides on installing OpenPhoto on your webhost.
+
+*OpenPhoto should be installed in the root directory of a domain or subdomain.*
+
+Variables:
+
+- *OpenPhotoRoot*: the root directory for OpenPhoto (e.g., ~/openphoto)
+
+### Before you install OpenPhoto
+This guide assumes you have:
+* Checked that your webhost supports MySQL and PHP
+* Shell or FTP access to your web server
+* An FTP or SSH client
+* A web browser of choice
+* An external cloud service account on Amazon or Dropbox (if you want to store your photos there)
+
+
+### The short version
+Here's the short version of the instructions for those already comfortable with installing software on a web server. You can check out the detailed instructions below for more information on each step.
+
+1. Download the latest version of OpenPhoto from Github and extract it to the root folder of your website. <a href="https://github.com/photo/frontend/archive/master.zip">Direct link to latest version as a .zip file</a>
+
+2. Prepare your cloud storage option and have your credentials ready. (Optional)
+
+3. Create a new MySQL database and a new user for that database. Remember the hostname (the default should be fine), database name, username, and password. Your webhost may have a MySQL control panel such as PhpMyAdmin that you can do this in.
+
+4. Create the following folders and chmod them to 775:
+
+        mkdir OpenPhotoRoot/src/html/assets/cache
+        chmod 775 OpenPhotoRoot/src/html/assets/cache
+        
+        mkdir OpenPhotoRoot/src/html/photos
+        chmod 775 OpenPhotoRoot/src/html/photos
+        
+        mkdir OpenPhotoRoot/src/userdata
+        chmod 775 OpenPhotoRoot/src/userdata
+        
+5. Visit your website and follow the instructions. 
+
+That's it! OpenPhoto should now be installed. Because there are so many special cases specific to individual webhosts along with things that could go wrong, you may want to read the full instructions below.
+
+### The detailed version
+
+#### 1. Download OpenPhoto from Github.
+<a href="https://github.com/photo/frontend/archive/master.zip">Direct link to latest version as a .zip file</a>. You can also do the following:
+
+        wget https://github.com/photo/frontend/tarball/master -O openphoto.tar.gz
+        tar -zxvf openphoto.tar.gz
+        mv openphoto-frontend-* OpenPhotoRoot
+
+#### 2. Install any dependencies or modules needed.
+Your webhost may include them by default. Check their documentation. Here's what you'll need:
+
+* The Pecl extension oauth for authentication
+* ImageMagick or GD for photo rendering
+
+The method of installing these varies by webhost. Some webhosts let you install them by yourself; others will install these for you if you contact them.
+
+#### 3. Create your cloud accounts (optional).
+Create an account at <a href="https://aws.amazon.com/s3">Amazon AWS</a> or <a href="http://www.dropbox.com">Dropbox</a> if you plan to use them. Create a new bucket (S3) or app (Dropbox). Save your keys since you'll need them soon.  
+
+At Amazon:    
+* Sign in and visit <a href="https://console.aws.amazon.com/s3/home">the S3 panel</a> and select Create a New Bucket. 
+* Give your bucket a name and select a region, then select Create. 
+* <a href="https://portal.aws.amazon.com/gp/aws/securityCredentials">Obtain your access keys</a> and save them.
+
+At Dropbox:
+* Sign in and create a folder for your photos to go in. 
+* Visit <a href="https://www.dropbox.com/developers/apps">the developers page</a>
+* Select Create an App, and select Core API for App Type and Full Dropbox Access.
+
+This will give you a development app to use for your photos. Save your access keys; you'll need them soon.
+
+#### 4. Create a database and user.
+Visit your control panel for managing databases and create a new database and new user for the database. Give the user `CREATE DATABASE` privileges. Remember the hostname (the default should be fine), database name, username, and password. You'll need these during setup.
+
+#### 5. Configure the subdomain or domain.
+You may have to add the domain if you're bringing in a new domain. Consult your webhost's documentation if needed. Depending on your webhost you may have to visit multiple areas of the site to configure everything, or you may have to configure these separately. But here's what you need to set up.
+
+* PHP: Select the latest version, FastCGI configuration if available
+* Web directory: OpenPhotoRoot/src/html
+
+#### 6. Upload OpenPhoto.
+Upload the contents of the downloaded OpenPhoto folder to OpenPhotoRoot if you haven't already done that. You can do this with an FTP or SSH client.
+
+#### 7. Create the following directories.
+
+        the cache:
+        mkdir OpenPhotoRoot/src/html/assets/cache
+        chmod 775 OpenPhotoRoot/src/html/assets/cache
+        
+        to store your photos if you're planning on local storage:
+        mkdir OpenPhotoRoot/src/html/photos
+        chmod 775 OpenPhotoRoot/src/html/photos
+        
+        to store userdata:
+        mkdir OpenPhotoRoot/src/userdata
+        chmod 775 OpenPhotoRoot/src/userdata
+
+#### 8. Install OpenPhoto
+After waiting a sufficient amount of time for the subdomain name to propagate, use the browser to connect to the new subdomain.  You should see a setup page for OpenPhoto which will allow you to configure your OpenPhoto project.
+
+* Enter your email address and select a password.
+
+* Select your image renderer (ImageMagick or GD are the most common options), database (MySQL or InnoDB), and storage (Local filesystem, Amazon S3, Amazon S3+Dropbox, Local filesystem+Dropbox).
+
+* Enter your credentials for your database, Amazon S3, or Dropbox.
+
+**ENJOY!**
+
+### Troubleshooting
+
+#### Setup page looks strange (black and white, unstyled)
+If the setup page is not colorful and well formatted, then the css and javascript files are most likely not being loaded.  Possible causes:
+
+- Web directory root is not properly set (check control panel for the subdomain)
+- src/html/assets/cache directory is not writeable by Apache (check your permissions)
+
+#### My webhost doesn't recognize OpenPhotoRoot/src/html as the index directory.
+You can set this in the .htaccess page at OpenPhotoRoot/src. If your webhost lets you set this through the web panel you can also do that there.
+
+#### Error setting up the database
+Double check all the parameters. Check your database control panel and verify that everything is correct. Also double check that the user for your database has permission to create a database.