You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@guacamole.apache.org by mj...@apache.org on 2016/04/26 21:57:01 UTC
[1/2] incubator-guacamole-website git commit: Add license boilerplate
to _config.yml.
Repository: incubator-guacamole-website
Updated Branches:
refs/heads/master 658bc767a -> c47a2e19a
Add license boilerplate to _config.yml.
Project: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/commit/30834f4c
Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/tree/30834f4c
Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/diff/30834f4c
Branch: refs/heads/master
Commit: 30834f4ca6a29c85c1eb5f66247a92c5323cd969
Parents: 658bc76
Author: Michael Jumper <mj...@apache.org>
Authored: Tue Apr 26 11:44:27 2016 -0700
Committer: Michael Jumper <mj...@apache.org>
Committed: Tue Apr 26 11:44:27 2016 -0700
----------------------------------------------------------------------
_config.yml | 18 ++++++++++++++++++
1 file changed, 18 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/30834f4c/_config.yml
----------------------------------------------------------------------
diff --git a/_config.yml b/_config.yml
index 49af3c7..1c66f79 100644
--- a/_config.yml
+++ b/_config.yml
@@ -1,3 +1,21 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
# Site settings
title: Apache Guacamole
[2/2] incubator-guacamole-website git commit: Add README.md and
exclude from Jekyll build.
Posted by mj...@apache.org.
Add README.md and exclude from Jekyll build.
Project: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/commit/c47a2e19
Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/tree/c47a2e19
Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/diff/c47a2e19
Branch: refs/heads/master
Commit: c47a2e19a6b779a54240ed37df9032c31ac39630
Parents: 30834f4
Author: Michael Jumper <mj...@apache.org>
Authored: Tue Apr 26 12:56:46 2016 -0700
Committer: Michael Jumper <mj...@apache.org>
Committed: Tue Apr 26 12:56:46 2016 -0700
----------------------------------------------------------------------
README.md | 149 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
_config.yml | 1 +
2 files changed, 150 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/c47a2e19/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1b53acd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,149 @@
+The Apache Guacamole website
+============================
+
+This repository contains the source for the website of Apache Guacamole, a
+clientless remote desktop solution currently undergoing incubation at the
+Apache Incubator.
+
+The website itself is completely static, being automatically generated by
+[Jekyll](https://jekyllrb.com/) prior to deployment. The content of the website
+is written in a mixture of HTML and Markdown, with dynamic portions written
+using [liquid templating](https://jekyllrb.com/docs/templates/). Templated
+content is interpreted only a build time, with the final result being
+completely static.
+
+To facilitate ease of development and testing, this repository also contains a
+build script, `build.sh`, the usage of which is documented below.
+
+Table of contents
+-----------------
+
+* [Repository structure](#repository-structure)
+* [Build prerequisites](#build-prerequisites)
+* [Testing changes locally](#testing-changes-locally)
+* [Publishing changes](#publishing-changes)
+
+Repository structure
+--------------------
+
+In addition to the `LICENSE` and `NOTICE` files required of any proper Apache-
+licensed project, the repository contains the following critical files:
+
+| Filename | Description
+| ------------- | -----------
+| `_config.yml` | Configuration information controlling the Jekyll build. This is a standard Jekyll file. See: [Jekyll directory structure](https://jekyllrb.com/docs/structure/)
+| `build.sh` | The website build script (usage documented below).
+| `doc/` | Per-release documentation for Apache Guacamole. This directory contains one subdirectory per release, where each subdirectory contains the overall manual (`.../gug/`) API documentation for each part of the Guacamole core (`.../libguac/`, `.../guacamole-common/`, etc.). Files in this directory are not interpreted by Jekyll, as there are far too many files for this to be reasonable. They are instead copied into place by the `build.sh` script.
+| `images/` | Images which are referenced within the website HTML and CSS.
+| `pub/` | Miscellaneous public files, such as test scripts. The test scripts in this directory have historically been shared to users to help with debugging.
+| `styles/` | All CSS files referenced by the website HTML.
+| `_includes/` | Common HTML fragments used by Jekyll and referenced in other templates, such as the website header and footer. These *must* be HTML only. This is a standard Jekyll directory. See: [Jekyll directory structure](https://jekyllrb.com/docs/structure/)
+| `_layouts/` | Templates describing the structure of different types of content. This is a standard Jekyll directory. See: [Jekyll directory structure](https://jekyllrb.com/docs/structure/)
+| `_links/` | Documents which contain metadata describing the links which should appear in the site navigation menu. The documents here are completely empty except for the metadata.
+| `_releases` | Release notes for Guacamole releases, including metadata describing the files and documentation associated with those releases.
+
+Build prerequisites
+-------------------
+
+The build depends entirely on Jekyll, thus this must be installed first. If you
+do not yet have Jekyll installed, please see [Jekyll's own installation
+instructions](https://jekyllrb.com/docs/installation/) to get started.
+
+Beyond Jekyll, you will also need:
+
+* A POSIX-compliant implementation of `sh` (to run `build.sh`)
+* git (to clone this repository and to publish changes)
+* `mktemp` (used by `build.sh` when staging changes prior to publishing)
+
+The `build.sh` script will check whether the required programs are installed,
+and will fail early with an appropriate message if a required program cannot be
+found.
+
+The build script handles three primary variations of common build tasks:
+
+1. The build itself, when invoked as `./build.sh`. This invokes Jekyll and recursively copies the `doc/` (part of the website source) and `_site/` (generated by Jekyll during the build) to the `content/` directory.
+2. Serving a local copy of the website, when invoked as `./build.sh PORT`.
+3. Staging local changes for commit to the special "asf-git" branch, when invoked as `./build.sh stage`. Once changes are committed and pushed to "asf-git", the public website will be updated by the ASF's gitpubsub.
+
+Testing changes locally
+-----------------------
+
+To test your changes to the website, you can either invoke `./build.sh` to build a static copy of the site to the `content/` subdirectory, or invoke `./build.sh PORT` (where `PORT` a TCP port number) to both build the static copy of the site *and* run Ruby's web server to serve `content/` locally at the given port:
+
+ $ ./build.sh 8080
+ Configuration file: /home/mjumper/apache-guacamole/incubator-guacamole-website/_config.yml
+ Source: /home/mjumper/apache-guacamole/incubator-guacamole-website
+ Destination: /home/mjumper/apache-guacamole/incubator-guacamole-website/_site
+ Incremental build: disabled. Enable with --incremental
+ Generating...
+ done in 0.563 seconds.
+ Auto-regeneration: disabled. Use --watch to enable.
+ Copying "doc/" and built site to "content/" ...
+ Done. Full site is now within the "content/" directory.
+ [2016-04-26 12:35:36] INFO WEBrick 1.3.1
+ [2016-04-26 12:35:36] INFO ruby 2.1.7 (2015-08-18) [x86_64-linux]
+ [2016-04-26 12:35:36] INFO WEBrick::HTTPServer#start: pid=18927 port=8080
+
+When done testing your local changes, press `Ctrl` + `C` to stop the
+web server and return to the shell.
+
+Publishing changes
+------------------
+
+Changes to the website are published using Apache's
+[gitpubsub](https://blogs.apache.org/infra/entry/git_based_websites_available)
+which relies on a special branch called "asf-git" containing *all website
+content* within a directory called `content/`.
+
+In the Apache Guacamole website repository, the "asf-git" branch is an "orphan"
+branch. The branch has no commits in common with the "master" branch and
+consists solely of the `content/` subdirectory. Updating the website thus
+involves:
+
+1. Making and testing your changes locally
+2. Replacing the entire contents of the `content/` directory within "asf-git"
+ with the newly-generated `content/` directory.
+
+The `build.sh` script can take care of all this for you when invoked as
+`./build.sh stage`:
+
+ $ ./build.sh stage
+ Configuration file: /home/mjumper/apache-guacamole/incubator-guacamole-website/_config.yml
+ Source: /home/mjumper/apache-guacamole/incubator-guacamole-website
+ Destination: /home/mjumper/apache-guacamole/incubator-guacamole-website/_site
+ Incremental build: disabled. Enable with --incremental
+ Generating...
+ done in 0.568 seconds.
+ Auto-regeneration: disabled. Use --watch to enable.
+ Copying "doc/" and built site to "content/" ...
+ Done. Full site is now within the "content/" directory.
+ Switched to branch 'asf-git'
+ Removing README.md
+ Removing _site/
+ Content staged for commit. Use git to commit the results when ready.
+ NOTE: The build.sh script will no longer exist. To serve the staged
+ contents, run:
+
+ ruby -run -e httpd content/ -p PORT
+
+ where PORT is the port number where the HTTP server should listen.
+ $
+
+At this point, you will be on the "asf-git" branch and the current directory
+will contain only the `content/` subdirectory:
+
+ $ ls
+ content
+ $
+
+Keep in mind that the new content is only *staged* for commit. It has not yet
+been committed. Once you have verified that the staged content is as expected,
+commit your changes (along with a useful commit message describing the changes
+at a high level) using `git commit` and publish the update using
+`git push origin`.
+
+If you wish to unstage your changes, use `git reset --hard HEAD` to return to
+the original state of "asf-git", wiping out any local modifications made by
+`build.sh`. You can then return to whichever branch you were working on with
+`git checkout`.
+
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/c47a2e19/_config.yml
----------------------------------------------------------------------
diff --git a/_config.yml b/_config.yml
index 1c66f79..c21c2d0 100644
--- a/_config.yml
+++ b/_config.yml
@@ -23,6 +23,7 @@ title: Apache Guacamole
# Build settings
markdown: kramdown
exclude:
+ - README.md
- build.sh
- content
- doc