2017/README.md

   1 LibrePlanet 2017
   2 ================
   3
   4 ##### SECTION 1: DEVELOPMENT WORKFLOW #####
   5
   6 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.
   7
   8 Full workflow to make, test and deploy an edit
   9 -----------------
  10
  11 * Check out the master branch and make sure it is up to date with stable.
  12   * git checkout master
  13 * 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.
  14 * Make your edits. (See instructions for editing content below.)
  15 * Optionally, test them on your computer with a local development environment. (See instructions below for setting up your development environment).
  16 * If you are working on your own branch created for your edit, merge, your branch into master, then push master.
  17   * git checkout master
  18   * git merge BRANCHNAME
  19   * git push
  20 * Review the edited version of the site at http://wiki-dev0.libreplanet.org/YEAR. You can share this with others.
  21 * When you are satisfied, merge master into stable and then push stable. Your edits are now live.
  22   * git checkout stable
  23   * git merge master
  24   * git push
  25
  26 ##### SECTION 2: EDITING INSTRUCTIONS #####
  27
  28 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.
  29
  30 Creating a New Page
  31 -------------------
  32
  33 *Boilerplate*
  34
  35 Add the following to your new page (it should remain commented out, as that is the syntax for SSI):
  36
  37 ```
  38 <!--#include virtual="/2017/includes/header.html"-->
  39 <!--#include virtual="/2017/includes/banner.html"-->
  40 <!--#include virtual="/2017/includes/sidebar.html"-->
  41 <!--#include virtual="/2017/includes/footer.html"-->
  42 <!--#include virtual="/2017/includes/close.html"-->
  43 ```
  44
  45 This will include the header, banner, sidebar, footer and closing tags
  46 saving you from duplicating HTML.
  47
  48 If JS is needed for a page, then create a file, containing the JS
  49 includes, in `/2017/includes/` & use SSI to include it in the page.
  50
  51 Use `/2017/includes/boilerplate.html` to start a new page.
  52
  53 *Add Your Markup*
  54
  55 Add HTML markup in-between the sidebar and footer includes.
  56
  57 *Enable SSI*
  58
  59 Files that contain include directives must be marked as executable
  60 otherwise Apache will not parse them.  (The directive `XBitHack on` in the .conf file pasted above enables this behavior).
  61
  62 To mark a file as executable, run:
  63
  64 ```
  65 chmod +x foo.html
  66 ```
  67
  68 Replace `foo.html` with the desired file name.
  69
  70 Modifying top-right corner
  71 --------------------------
  72
  73 In the `/2017/includes/banner.html` find the `...#top-right-desktop
  74 start...` section.
  75
  76 *For register now*
  77
  78 Include `register-now.html`
  79
  80     <!-- #top-right-desktop start -->
  81     <!--#include virtual="/2017/includes/register-now.html"-->
  82     <!-- #top-right-desktop end -->
  83
  84 *For join LP list form*
  85
  86 Include `join-list.html`
  87
  88     <!-- #top-right-desktop start -->
  89     <!--#include virtual="/2017/includes/join-list.html"-->
  90     <!-- #top-right-desktop end -->
  91
  92
  93 ##### SECTION 3: SETTING UP A LOCAL DEVELOPMENT ENVIRONMENT #####
  94
  95 Apache is required in order to replicate the appearance of the website
  96 on the live and staging servers on your machine. If you don't want to
  97 install Apache, you can still work on the site, you just won't be able
  98 to see what it looks like until you push to the remote.
  99
 100 Modifying Apache's configuration files and running its executables
 101 typically requires root access.  So, you will most likely need to run
 102 the commands below as the root user using `sudo`.
 103
 104 *Enable server-side include module*
 105
 106 ```
 107 a2enmod include
 108 ```
 109
 110 If this doesn't work, you may not have Apache installed. Install the
 111 package apache2 from your package manager.
 112
 113 *Create virtual host*
 114
 115 Create a new file called libreplanet (libreplanet.conf for Apache 2.4) in `/etc/apache2/sites-available` with the following contents:
 116
 117 ```
 118 <VirtualHost *:80>
 119 RewriteEngine on
 120         ServerName local-dev.libreplanet.org
 121         ServerAdmin webmaster@localhost
 122         DocumentRoot /local-path/path-to-site
 123         <Directory /local-path/path-to-site/>
 124             Options Indexes FollowSymLinks MultiViews
 125             AllowOverride All
 126             Require all granted
 127             Order deny,allow
 128             deny from none
 129             allow from all
 130             SSILegacyExprParser on
 131             Options +Includes
 132             XBitHack on
 133         </Directory>
 134         ErrorLog /home/owner/libreplanet-static/logs/error.log
 135         CustomLog /home/owner/libreplanet-static/access.log combined
 136 </VirtualHost>
 137 ```
 138
 139 Replace all instances of `/path/to/libreplanet-static` with the full path to the root directory of your local
 140 git repository.
 141
 142 *Enable virtual host*
 143
 144 ```
 145 a2ensite your-virtual-host
 146 ```
 147
 148 Replace `your-virtual-host` with the name of virtual host file you made (in this case, libreplanet).
 149
 150 *Restart Apache*
 151
 152 ```
 153 service apache2 restart
 154 ```
 155
 156 *Edit your hosts file*
 157
 158 Edit your system's `/etc/hosts` file and add the following to the bottom:
 159
 160 ```
 161 127.0.0.1 lp2017.libreplanet.org
 162 ```
 163
 164 *Test*
 165
 166 Visit <http://lp2017.libreplanet.org/2017> in your web browser.  If
 167 everything is configured properly, you will see the LibrePlanet 2017
 168 site, complete with header, sidebar, and footer.