-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
------------------
+README version for LibrePlanet 2017
-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.
+Heads up: to edit the Web site, you'll need a basic-to-intermediate understanding of HTML, git, and command line.
-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`.
+# SECTION 1: DEVELOPMENT WORKFLOW
-### Enable server-side include module
+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.
-```
-a2enmod include
-```
+Full workflow to make, test and deploy an edit.
+-----------------
-If this doesn't work, you may not have Apache installed. Install the
-package apache2 from your package manager.
+* Check out the master branch and make sure it is up to date with origin/master by doing:
+ * git checkout master
+ * git pull
+* 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.
+* Make your edits. (See site structure and 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 by doing:
+ * git checkout master
+ * git merge BRANCHNAME
+* Push master by doing:
+ * 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 by doing:
+ * git checkout stable
+ * git merge master
+ * git push
+* Your edits are now live and visible at libreplanet.org/YEAR
-### Create virtual host
+# SECTION 2: SITE STRUCTURE
-Create a new file called libreplanet (libreplanet.conf for Apache 2.4) in `/etc/apache2/sites-available` with the following contents:
+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".
-```
-<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>
-```
+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.
-Replace all instances of `/path/to/libreplanet-static` with the full path to the root directory of your local
-git repository.
+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.
-### Enable virtual host
+# SECTION 3: EDITING INSTRUCTIONS
-```
-a2ensite your-virtual-host
-```
+To change content on existing pages, use your favorite text editor.
-Replace `your-virtual-host` with the name of virtual host file you made (in this case, libreplanet).
+Here are specific instructions for more complex editing tasks:
-### Restart Apache
+## Editing the schedule or bios pages
-```
-service apache2 restart
-```
+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.
-### Edit your hosts file
+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.
-Edit your system's `/etc/hosts` file and add the following to the bottom:
-
-```
-127.0.0.1 lp2017.libreplanet.org
-```
-
-### 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.
+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.
-Creating a New Page
--------------------
+## 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):
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).
Replace `foo.html` with the desired file name.
-Modifying top-right corner
---------------------------
+## 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`
<!--#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`
<!--#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 4: 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*
-When you're happy with the state of the master branch and want to
-deploy live, do the following:
+```
+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:
```
-git checkout stable
-git merge master
-git push
+<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>
```
-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>.
+Replace all instances of `/path/to/libreplanet-static` with the full path to the root directory of your local
+git repository.
-CSS and JavaScript
-------------------
+*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
+```
+
+*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.
-This site is built with:
+# SECTION 5: TROUBLESHOOTING
+* I'm doing everything right, but the Web site isn't updating.
-* [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)
+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.
projects / libreplanet-static.git / blobdiff