2018/README.md

   1 README version for LibrePlanet 2018
   2
   3 Heads up: to edit the Web site, you'll need a basic-to-intermediate understanding of HTML, git, and command line.
   4
   5 # SECTION 1: DEVELOPMENT WORKFLOW
   6
   7 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.
   8
   9 Full workflow to make, test and deploy an edit.
  10 -----------------
  11
  12 * Check out the master branch and make sure it is up to date with origin/master by doing:
  13   * git checkout master
  14   * git pull
  15 * Is 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.
  16 * Make your edits. (See site structure and instructions for editing content below.)
  17 * Optionally, test them on your computer with a local development environment. (See instructions below for setting up your development environment).
  18 * If you are working on your own branch created for your edit, merge, your branch into master by doing:
  19   * git checkout master
  20   * git merge BRANCHNAME
  21 * Push master by doing:
  22   * git push
  23 * Review the edited version of the site at http://wiki-dev0.libreplanet.org/YEAR. You can share this with others.
  24 * When you are satisfied, merge master into stable and then push stable by doing:
  25   * git checkout stable
  26   * git merge master
  27   * git push
  28 * Your edits are now live and visible at libreplanet.org/YEAR
  29
  30 # SECTION 2: SITE STRUCTURE
  31
  32 The site is made up of HTML files, each representing part of a page (sidebar, content, footer, etc.). When a browser visits the site, the server finds the core HTML file for the page (for example, the core file for https://www.libreplanet.org/YEAR/getting-around is /YEAR/getting-around/index.html in the repo), then reads special comments in that file to which instruct it to pull various other HTML files in to produce a complete page, using an Apache feature called SSI. To edit part of a page, you will need to find out which HTML file contains the element in question. Do this by navigating to core HTML file and exploring the comments that start with "#include".
  33
  34 The bios page and the sessions page are maintained through a special workflow to make it easy to have only one canonical copy edited by humans. That canonical copy is saved in brains (the FSF's internal wiki) in a special format. To update the sites' sessions page or bios page, you will need the lps_gen program installed on your computer (<https://ricketyspace.net/lpschedule-generator/>), as well as a local checkout of the SVN repository that contains brains.
  35
  36 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.
  37
  38 # SECTION 3: EDITING INSTRUCTIONS
  39
  40 To change content on existing pages, use your favorite text editor.
  41
  42 Here are specific instructions for more complex editing tasks:
  43
  44 ## Editing the schedule or bios pages
  45
  46 The workflow for this is Edit the Brains page with the schedule, then run a script to convert it into HTML and dump it into your checkout of the repo, then push that change up to the Web like any other edit.
  47
  48 See instructions at <https://ricketyspace.net/lpschedule-generator> for installing and running the script. The source files are stored in Brains in markdown but with special tags, so that you can edit them without needing to know this whole process.
  49
  50 Please crop all photos of speakers too 100x100 px (200x200 px for keynotes) and then upload them to <http://static.fsf.org/nosvn/libreplanet/speaker-pics/>. Then include their URL in the bios page to embed them.
  51
  52 ## Creating a New Page
  53
  54 *Boilerplate*
  55
  56 Add the following to your new page (it should remain commented out, as that is the syntax for SSI):
  57
  58 ```
  59 <!--#include virtual="/2018/includes/header.html"-->
  60 <!--#include virtual="/2018/includes/banner.html"-->
  61 <!--#include virtual="/2018/includes/sidebar.html"-->
  62 <!--#include virtual="/2018/includes/footer.html"-->
  63 <!--#include virtual="/2018/includes/close.html"-->
  64 ```
  65
  66 This will include the header, banner, sidebar, footer and closing tags
  67 saving you from duplicating HTML.
  68
  69 If JS is needed for a page, then create a file, containing the JS
  70 includes, in `/2018/includes/` & use SSI to include it in the page.
  71
  72 Use `/2018/includes/boilerplate.html` to start a new page.
  73
  74 *Add Your Markup*
  75
  76 Add HTML markup in-between the sidebar and footer includes.
  77
  78 *Enable SSI*
  79
  80 Files that contain include directives must be marked as executable
  81 otherwise Apache will not parse them.  (The directive `XBitHack on` in the .conf file pasted above enables this behavior).
  82
  83 To mark a file as executable, run:
  84
  85 ```
  86 chmod +x foo.html
  87 ```
  88
  89 Replace `foo.html` with the desired file name.
  90
  91 ## Modifying top-right corner
  92
  93 In the `/2018/includes/banner.html` find the `...#top-right-desktop
  94 start...` section.
  95
  96 *For register now*
  97
  98 Include `register-now.html`
  99
 100     <!-- #top-right-desktop start -->
 101     <!--#include virtual="/2018/includes/register-now.html"-->
 102     <!-- #top-right-desktop end -->
 103
 104 *For join LP list form*
 105
 106 Include `join-list.html`
 107
 108     <!-- #top-right-desktop start -->
 109     <!--#include virtual="/2018/includes/join-list.html"-->
 110     <!-- #top-right-desktop end -->
 111
 112
 113 # SECTION 4: SETTING UP A LOCAL DEVELOPMENT ENVIRONMENT
 114
 115 Apache is required in order to replicate the appearance of the website
 116 on the live and staging servers on your machine. If you don't want to
 117 install Apache, you can still work on the site, you just won't be able
 118 to see what it looks like until you push to the remote.
 119
 120 Modifying Apache's configuration files and running its executables
 121 typically requires root access.  So, you will most likely need to run
 122 the commands below as the root user using `sudo`.
 123
 124 *Enable required modules*
 125
 126 ```
 127 a2enmod include rewrite
 128 ```
 129
 130 If this doesn't work, you may not have Apache installed. Install the
 131 package apache2 from your package manager.
 132
 133 *Create virtual host*
 134
 135 Create a new file called libreplanet.conf in `/etc/apache2/sites-available` with the following contents:
 136
 137 ```
 138 <VirtualHost *:80>
 139 RewriteEngine on
 140         ServerName local-dev.libreplanet.org
 141         ServerAdmin webmaster@localhost
 142         DocumentRoot /path-to-site
 143         <Directory /path-to-site/>
 144             Options Indexes FollowSymLinks MultiViews
 145             AllowOverride All
 146             Require all granted
 147             Order deny,allow
 148             deny from none
 149             allow from all
 150             SSILegacyExprParser on
 151             Options +Includes
 152             XBitHack on
 153         </Directory>
 154         ErrorLog /path-to-site/logs/error.log
 155         CustomLog /path-to-site/logs/access.log combined
 156 </VirtualHost>
 157 ```
 158
 159 Replace all instances of `/path-to-site` and  with the full path to the root directory of your local
 160 git repository.
 161
 162 * Create the logs directory, as a normal user *
 163 ```
 164 mkdir /path-to-site/logs
 165 chmod 777 /path-to-site/logs
 166 ```
 167
 168
 169 *Enable virtual host*
 170
 171 ```
 172 a2ensite libreplanet
 173 ```
 174
 175 Replace `your-virtual-host` with the name of virtual host file you made (in this case, libreplanet).
 176
 177 *Restart Apache*
 178
 179 ```
 180 service apache2 restart
 181 *  /etc/init.d/apache2 restart
 182
 183 ```
 184
 185 *Edit your hosts file*
 186
 187 Edit your system's `/etc/hosts` file and add to the line starting with
 188 127.0.0.1: `local-dev.libreplanet.org`
 189
 190
 191 *Test*
 192
 193 Visit <http://local-dev.libreplanet.org/2018> in your web browser.  If
 194 everything is configured properly, you will see the LibrePlanet 2018
 195 site, complete with header, sidebar, and footer.
 196
 197 # SECTION 5: TROUBLESHOOTING
 198 * I'm doing everything right, but the Web site isn't updating.
 199
 200 Ask the tech team to look at the git hook that publishes to the live site. When you push to the git repository, this hook is supposed to update what is actually served on the Internet to match the repo.
 201
 202 * The website isn't loading! What?
 203
 204 It might be a permissions issue. Try cd / ls -lad to check permissions. If they are not right, chmod 711 . should fix it