From: Zak Rogoff Date: Tue, 29 Nov 2016 20:40:56 +0000 (-0500) Subject: Improving README file. X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=60bc02024797f6e4d910d616bc6a74feb4c9fdbd;p=libreplanet-static.git Improving README file. --- diff --git a/2017/README.md b/2017/README.md index f2026705..8d53a705 100644 --- a/2017/README.md +++ b/2017/README.md @@ -1,100 +1,36 @@ 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 (), -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 -(). - -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: - -``` - -RewriteEngine on - ServerName local-dev.libreplanet.org - ServerAdmin webmaster@localhost - DocumentRoot /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 - - ErrorLog /home/owner/libreplanet-static/logs/error.log - CustomLog /home/owner/libreplanet-static/access.log combined - -``` - -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 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` -### For join LP list form. +*For join LP list form* Include `join-list.html` @@ -153,31 +89,80 @@ Include `join-list.html` -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 . When you push to the -`stable` branch, the site is deployed to . +##### 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: + +``` + +RewriteEngine on + ServerName local-dev.libreplanet.org + ServerAdmin webmaster@localhost + DocumentRoot /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 + + ErrorLog /home/owner/libreplanet-static/logs/error.log + CustomLog /home/owner/libreplanet-static/access.log combined + +``` + +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 -. +*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 in your web browser. If +everything is configured properly, you will see the LibrePlanet 2017 +site, complete with header, sidebar, and footer.