Improving README file.
authorZak Rogoff <zak@fsf.org>
Tue, 29 Nov 2016 20:40:56 +0000 (15:40 -0500)
committerZak Rogoff <zak@fsf.org>
Tue, 29 Nov 2016 20:40:56 +0000 (15:40 -0500)
2017/README.md

index f2026705168d900271fc342d4e36dfe27e4fdd3b..8d53a705c8f8dd8ca1b047f79b19069df89682e0 100644 (file)
 LibrePlanet 2017
 ================
 
-This is the static HTML site for LibrePlanet 2017.  Read on for
-instructions on how to setup your development environment.
-
-The repository has a master (development) branch and a stable
-(live) branch. To work on it, you'll edit your checkout of the
-master branch until you are satisfied, push it to the master
-branch on the Web server (<http://wiki-dev0.libreplanet.org>),
-make sure it works well and make sure it works well. Then
-you'll copy it over to your checkout of the stable branch,
-then push that to the stable branch on the Web server
-(<http://libreplanet.org>).
-
-Setting Up Apache
------------------
+##### SECTION 1: DEVELOPMENT WORKFLOW #####
 
-Apache is required in order to replicate the appearance of the website
-on the live and staging servers on your machine. If you don't want to
-install Apache, you can still work on the site, you just won't be able
-to see what it looks like until you push to the remote.
-
-Modifying Apache's configuration files and running its executables
-typically requires root access.  So, you will most likely need to run
-the commands below as the root user using `sudo`.
-
-### Enable server-side include module
-
-```
-a2enmod include
-```
-
-If this doesn't work, you may not have Apache installed. Install the
-package apache2 from your package manager.
+The actual LIVE site, visible at libreplanet.org/YEAR, is served from the "stable" branch of the git repository using a git hook. There is also a development branch called "master" which we use to preview edits on the Web. The master branch is served to the Web at http://wiki-dev0.libreplanet.org/YEAR and publicly visible, but not linked to.
 
-### Create virtual host
-
-Create a new file called libreplanet (libreplanet.conf for Apache 2.4) in `/etc/apache2/sites-available` with the following contents:
-
-```
-<VirtualHost *:80>
-RewriteEngine on
-        ServerName local-dev.libreplanet.org
-        ServerAdmin webmaster@localhost
-        DocumentRoot /local-path/path-to-site
-        <Directory /local-path/path-to-site/>
-            Options Indexes FollowSymLinks MultiViews
-            AllowOverride All
-            Require all granted
-            Order deny,allow
-            deny from none
-            allow from all
-            SSILegacyExprParser on
-            Options +Includes
-            XBitHack on
-        </Directory>
-        ErrorLog /home/owner/libreplanet-static/logs/error.log
-        CustomLog /home/owner/libreplanet-static/access.log combined
-</VirtualHost>
-```
-
-Replace all instances of `/path/to/libreplanet-static` with the full path to the root directory of your local
-git repository.
-
-### Enable virtual host
-
-```
-a2ensite your-virtual-host
-```
-
-Replace `your-virtual-host` with the name of virtual host file you made (in this case, libreplanet).
-
-### Restart Apache
-
-```
-service apache2 restart
-```
-
-### Edit your hosts file
-
-Edit your system's `/etc/hosts` file and add the following to the bottom:
-
-```
-127.0.0.1 lp2017.libreplanet.org
-```
+Full workflow to make, test and deploy an edit
+-----------------
 
-### Test
-
-Visit <http://lp2017.libreplanet.org/2017> in your web browser.  If
-everything is configured properly, you will see the LibrePlanet 2017
-site, complete with header, sidebar, and footer.
+* Check out the master branch and make sure it is up to date with stable.
+  * git checkout master
+* If this a large edit or a small edit? If it is small, edit, work in master. If this is a large edit that will take longer than a day, make a new branch based on the master branch and work there.
+* Make your edits. (See instructions for editing content below.)
+* Optionally, test them on your computer with a local development environment. (See instructions below for setting up your development environment).
+* If you are working on your own branch created for your edit, merge, your branch into master, then push master.
+  * git checkout master
+  * git merge BRANCHNAME
+  * git push
+* Review the edited version of the site at http://wiki-dev0.libreplanet.org/YEAR. You can share this with others.
+* When you are satisfied, merge master into stable and then push stable. Your edits are now live.
+  * git checkout stable
+  * git merge master
+  * git push
+
+##### SECTION 2: EDITING INSTRUCTIONS #####
+
+This site is built with [Bootstrap 3.3.5](https://github.com/twbs/bootstrap/releases/download/v3.3.5/bootstrap-3.3.5-dist.zip) and [jQuery 1.11.1](http://code.jquery.com/jquery-1.11.3.js) but you do not need to understand either of these technologies to make minor content edits to the site.
 
 Creating a New Page
 -------------------
 
-### Boilerplate
+*Boilerplate*
 
 Add the following to your new page (it should remain commented out, as that is the syntax for SSI):
 
@@ -114,11 +50,11 @@ includes, in `/2017/includes/` & use SSI to include it in the page.
 
 Use `/2017/includes/boilerplate.html` to start a new page.
 
-### Add Your Markup
+*Add Your Markup*
 
 Add HTML markup in-between the sidebar and footer includes.
 
-### Enable SSI
+*Enable SSI*
 
 Files that contain include directives must be marked as executable
 otherwise Apache will not parse them.  (The directive `XBitHack on` in the .conf file pasted above enables this behavior).
@@ -137,7 +73,7 @@ Modifying top-right corner
 In the `/2017/includes/banner.html` find the `...#top-right-desktop
 start...` section.
 
-### For register now
+*For register now*
 
 Include `register-now.html`
 
@@ -145,7 +81,7 @@ Include `register-now.html`
     <!--#include virtual="/2017/includes/register-now.html"-->
     <!-- #top-right-desktop end -->
 
-### For join LP list form.
+*For join LP list form*
 
 Include `join-list.html`
 
@@ -153,31 +89,80 @@ Include `join-list.html`
     <!--#include virtual="/2017/includes/join-list.html"-->
     <!-- #top-right-desktop end -->
 
-Deploying to Staging/Live Servers
----------------------------------
 
-A system of git hooks automates deployment to the staging and live
-servers.  When you push to the `master` branch, the site is deployed
-to <http://wiki-dev0.libreplanet.org/2017>.  When you push to the
-`stable` branch, the site is deployed to <http://libreplanet.org>.
+##### SECTION 3: SETTING UP A LOCAL DEVELOPMENT ENVIRONMENT #####
+
+Apache is required in order to replicate the appearance of the website
+on the live and staging servers on your machine. If you don't want to
+install Apache, you can still work on the site, you just won't be able
+to see what it looks like until you push to the remote.
+
+Modifying Apache's configuration files and running its executables
+typically requires root access.  So, you will most likely need to run
+the commands below as the root user using `sudo`.
+
+*Enable server-side include module*
+
+```
+a2enmod include
+```
+
+If this doesn't work, you may not have Apache installed. Install the
+package apache2 from your package manager.
+
+*Create virtual host*
+
+Create a new file called libreplanet (libreplanet.conf for Apache 2.4) in `/etc/apache2/sites-available` with the following contents:
+
+```
+<VirtualHost *:80>
+RewriteEngine on
+        ServerName local-dev.libreplanet.org
+        ServerAdmin webmaster@localhost
+        DocumentRoot /local-path/path-to-site
+        <Directory /local-path/path-to-site/>
+            Options Indexes FollowSymLinks MultiViews
+            AllowOverride All
+            Require all granted
+            Order deny,allow
+            deny from none
+            allow from all
+            SSILegacyExprParser on
+            Options +Includes
+            XBitHack on
+        </Directory>
+        ErrorLog /home/owner/libreplanet-static/logs/error.log
+        CustomLog /home/owner/libreplanet-static/access.log combined
+</VirtualHost>
+```
+
+Replace all instances of `/path/to/libreplanet-static` with the full path to the root directory of your local
+git repository.
+
+*Enable virtual host*
+
+```
+a2ensite your-virtual-host
+```
+
+Replace `your-virtual-host` with the name of virtual host file you made (in this case, libreplanet).
 
-When you're happy with the state of the master branch and want to
-deploy live, do the following:
+*Restart Apache*
 
 ```
-git checkout stable
-git merge master
-git push
+service apache2 restart
 ```
 
-This merges the master branch with the stable branch, updates the
-remote repository on the git server, and triggers a deploy to
-<http://libreplanet.org>.
+*Edit your hosts file*
 
-CSS and JavaScript
-------------------
+Edit your system's `/etc/hosts` file and add the following to the bottom:
+
+```
+127.0.0.1 lp2017.libreplanet.org
+```
 
-This site is built with:
+*Test*
 
-* [Bootstrap 3.3.5](https://github.com/twbs/bootstrap/releases/download/v3.3.5/bootstrap-3.3.5-dist.zip)
-* [jQuery 1.11.1](http://code.jquery.com/jquery-1.11.3.js)
+Visit <http://lp2017.libreplanet.org/2017> in your web browser.  If
+everything is configured properly, you will see the LibrePlanet 2017
+site, complete with header, sidebar, and footer.