[docs][glossary] Add page that lists all standardized k8s terms (#5657)

* Add comprehensive glossary page Additional Authors: * Andrew Chen <chenopis@users.noreply.github.com> * Steve Perry <steveperry-53@users.noreply.github.com> * incorporate Tim's feedback * address zach's comments * address more comments * add additional crosslinking * Add platform developer, tweak formatting for disambiguation cases or multiparagraph definitions.
2017-10-12 16:12:38 -07:00
parent 8da72ca938
commit b22947afc3
55 changed files with 743 additions and 50 deletions
@@ -1,12 +0,0 @@
 - Fundamental
 - API Object
 - Metadata
 - Configuration
 - Security
 - Networking
 - Storage
 - Operation
 - Workload
 - Component
 - API
 - Extension
@@ -0,0 +1,3 @@
 id: architecture
 name: Architecture
 description: The inner components of Kubernetes.
@@ -0,0 +1,3 @@
 id: community
 name: Community
 description: Related to Kubernetes open-source development.
@@ -0,0 +1,3 @@
 id: core-object
 name: Core Object
 description: A resource type that Kubernetes supports by default.
@@ -0,0 +1,3 @@
 id: extension
 name: Extension
 description: Supported customizations of Kubernetes.
@@ -0,0 +1,3 @@
 id: fundamental
 name: Fundamental
 description: Relevant for a first-time user of Kubernetes.
@@ -0,0 +1,3 @@
 id: networking
 name: Networking
 description: How Kubernetes components talk to each other (and to programs outside the cluster).
@@ -0,0 +1,3 @@
 id: operation
 name: Operation
 description: Starting and maintaining Kubernetes.
@@ -0,0 +1,3 @@
 id: security
 name: Security
 description: Keeping Kubernetes applications safe and secure.
@@ -0,0 +1,3 @@
 id: storage
 name: Storage
 description: How Kubernetes applications handle persistent data.
@@ -0,0 +1,3 @@
 id: tool
 name: Tool
 description: Software that makes Kubernetes easier or better to use.
@@ -0,0 +1,3 @@
 id: user-type
 name: User Type
 description: Represents a common type of Kubernetes user.
@@ -0,0 +1,3 @@
 id: workload
 name: Workload
 description: Applications running on Kubernetes.
@@ -1,13 +1,13 @@
 id: _example
 name: Example K8s Term
-formerly:
+aka:
 - Slang K8s Term
 - Misnomer
 - Formerly Known as Prince
 related:
- Less Fancy K8s Term
+- id-of-less-fancy-k8s-term
- Tangential Term
+- id-of-tangential-term
- Commonly Used With
+- id-of-commonly-used-with-term
 tags:
 - Some Tag
 short-description: |
@@ -0,0 +1,11 @@
 id: application-architect
 name: Application Architect
 related:
  - application-developer
 tags:
  - user-type
 short-description: |
  A person responsible for the high-level design of an application.
 long-description: >
  An architect ensures that an app's implementation allows it to interact with its surrounding components in a scalable, maintainable way.
  Surrounding components include databases, logging infrastructure, and other microservices.
@@ -0,0 +1,11 @@
 id: application-developer
 name: Application Developer
 related:
  - application-architect
 tags:
  - user-type
 short-description: |
  A person who writes an application that runs in a Kubernetes cluster.
 long-description: >
  An application developer focuses on one part of an application.
  The scale of their focus may vary significantly in size.
@@ -0,0 +1,10 @@
 id: approver
 name: Approver
 tags:
 - community
 short-description: |
  A person who can review and approve Kubernetes code contributions.
 long-description: >
  While code review is focused on code quality and correctness, approval is focused on the holistic acceptance of a contribution.
  Holistic acceptance includes backwards/forwards compatibility, adhering to API and flag conventions, subtle performance and correctness issues, interactions with other parts of the system, and others.
  Approver status is scoped to a part of the codebase.
@@ -0,0 +1,8 @@
 id: cla
 name: CLA (Contributor License Agreement)
 tags:
 - community
 short-description: |
  Terms under which a [contributor](#term-contributor) grants a license to an open source project for their contributions.
 long-description: |
  CLAs help resolve legal disputes involving contributed material and intellectual property (IP).
@@ -0,0 +1,12 @@
 id: cluster-architect
 name: Cluster Architect
 related:
  - cluster
  - cluster-operator
 tags:
  - user-type
 short-description: |
  A person who designs infrastructure that involves one or more Kubernetes clusters.
 long-description: |
  Cluster architects are concerned with best practices for distributed systems, for example&#58; high availability and security.
@@ -0,0 +1,16 @@
 id: cluster-operator
 name: Cluster Operator
 aka:
  - Cluster Administrator
 related:
  - cluster
  - cluster-architect
 tags:
  - user-type
 short-description: |
  A person who configures, controls, and monitors clusters.
 long-description: |
  Their primary responsibility is keeping a cluster up and running, which may involve periodic maintenance activities or upgrades.<br>
  **NOTE:** Cluster operators are different from the [Operator pattern](https://coreos.com/operators) that extends the Kubernetes API.
@@ -0,0 +1,9 @@
 id: cluster
 name: Cluster
 tags:
 - fundamental
 - operation
 short-description: |
  A set of machines, called nodes, that run containerized applications managed by Kubernetes.
 long-description: |
  A cluster has several worker nodes and at least one master node.
@@ -0,0 +1,11 @@
 id: code-contributor
 name: Code Contributor
 aka:
  - Community Developer
 tags:
 - community
 - user-type
 short-description: |
  A person who develops and contributes code to the Kubernetes open source codebase.
 long-description: |
  They are also an active [community member](#term-community-member) who participates in one or more [Special Interest Groups (SIGs)](#term-sig).
@@ -0,0 +1,9 @@
 id: container
 name: Container
 tags:
 - fundamental
 - workload
 short-description: |
  A lightweight and portable executable image that contains software and all of its dependencies.
 long-description: |
  Containers decouple applications from underlying host infrastructure to make deployment easier in different cloud or OS environments, and for easier scaling.
@@ -0,0 +1,8 @@
 id: contributor
 name: Contributor
 tags:
 - community
 short-description: |
  Someone who donates code, documentation, or their time to help the Kubernetes project or community.
 long-description: |
  Contributions include pull requests (PRs), issues, feedback, [special interest group (SIG)](#term-sig) participation, or organizing community events.
@@ -0,0 +1,9 @@
 id: cronjob
 name: CronJob
 tags:
 - core-object
 - workload
 short-description: |
  Manages a [Job](/docs/concepts/jobs/run-to-completion-finite-workloads/) that runs on a periodic schedule.
 long-description: |
  Similar to a line in a *crontab* file, a [CronJob](/docs/concepts/workloads/controllers/cron-jobs/#writing-a-cron-job-spec) object specifies a schedule using the [Cron](https://en.wikipedia.org/wiki/Cron) format.
@@ -0,0 +1,10 @@
 id: deployment
 name: Deployment
 tags:
 - fundamental
 - core-object
 - workload
 short-description: |
  An API object that manages a replicated application.
 long-description: |
  Each replica is represented by a [Pod](#term-pod), and the Pods are distributed among the nodes of a cluster.
@@ -0,0 +1,15 @@
 id: developer
 name: Developer (disambiguation)
 aka:
  - Kubernetes Developer
 tags:
 - community
 - user-type
 short-description: |
  May refer to&#58; [*Application Developer*](#term-application-developer), [*Code Contributor*](#term-code-contributor), or [*Platform Developer*](#term-platform-developer).
 long-description: |
  This overloaded term may have different meanings depending on the context. It could mean&#58;
  * [**Application Developer**](#term-application-developer): A person who writes an application that runs in a Kubernetes cluster.
  * [**Code Contributor**](#term-code-contributor): A person who develops and contributes code to the Kubernetes open source codebase.
  * [**Platform Developer**](#term-platform-developer): A person who customizes the Kubernetes platform to fit the needs of their project&mdash;for example, by extending the API.
@@ -0,0 +1,11 @@
 id: downstream
 name: Downstream (disambiguation)
 related:
 - upstream
 tags:
 - community
 short-description: |
  May refer to: code in the Kubernetes ecosystem that depends upon the core Kubernetes codebase or a forked repo.
 long-description: |
  * In the **Kubernetes Community**: Conversations often use *downstream* to mean the ecosystem, code, or third-party tools that rely on the core Kubernetes codebase. For example, a new feature in Kubernetes may be adopted by applications *downstream* to improve their functionality.
  * In **GitHub** or **git**: The convention is to refer to a forked repo as *downstream*, whereas the source repo is considered *upstream*.
@@ -0,0 +1,9 @@
 id: helm-chart
 name: Helm Chart
 tags:
 - tool
 short-description: |
  A package of pre-configured Kubernetes resources that can be managed with the Helm tool.
 long-description: |
  Charts provide a reproducible way of creating and sharing Kubernetes applications.
  A single chart can be used to deploy something simple, like a memcached Pod, or something complex, like a full web app stack with HTTP servers, databases, caches, and so on.
@@ -0,0 +1,10 @@
 id: ingress
 name: Ingress
 tags:
 - networking
 - architecture
 - extension
 short-description: |
  An API object that manages external access to the services in a cluster, typically HTTP.
 long-description: |
  Ingress can provide load balancing, SSL termination and name-based virtual hosting.
@@ -0,0 +1,12 @@
 id: istio
 name: Istio
 tags:
 - networking
 - architecture
 - extension
 short-description: |
  An open platform (not Kubernetes-specific) that provides a uniform way to integrate microservices, manage traffic flow, enforce policies, and aggregate telemetry data.
 long-description: >
  Adding Istio does not require changing application code.
  It is a layer of infrastructure between a service and the network, which when combined with service deployments, is commonly referred to as a service mesh.
  Istio's control plane abstracts away the underlying cluster management platform, which may be Kubernetes, Mesosphere, etc.
@@ -0,0 +1,18 @@
 id: kops
 name: Kops
 tags:
 - tool
 - operation
 short-description: |
  A CLI tool that helps you create, destroy, upgrade and maintain production-grade, highly available, Kubernetes clusters. *NOTE&#58; Officially supports AWS only, with GCE and VMware vSphere in alpha*.
 long-description: |
  `kops` provisions your cluster with&#58;
    * Fully automated installation
    * DNS-based cluster identification
    * Self-healing&#58; everything runs in Auto-Scaling Groups
    * Limited OS support (Debian preferred, Ubuntu 16.04 supported, early support for CentOS & RHEL)
    * High availability (HA) support
    * The ability to directly provision, or generate terraform manifests
  You can also build your own cluster using [`kubeadm`](#term-kubeadm) as a building block. `kops` builds on the kubeadm work.
@@ -0,0 +1,9 @@
 id: kubeadm
 name: Kubeadm
 tags:
 - tool
 - operation
 short-description: |
  A tool for quickly installing Kubernetes and setting up a secure cluster.
 long-description: |
  You can use kubeadm to install both the control plane and the worker node components.
@@ -0,0 +1,9 @@
 id: kubectl
 name: Kubectl
 tags:
 - tool
 - fundamental
 short-description: |
  A command line tool for communicating with a [Kubernetes API](#term-kubernetes-api) server.
 long-description: |
  You can use kubectl to create, inspect, update, and delete Kubernetes objects.
@@ -0,0 +1,12 @@
 id: kubernetes-api
 name: Kubernetes API
 tags:
 - fundamental
 - architecture
 short-description: |
  The application that serves Kubernetes functionality through a RESTful interface and stores the state of the cluster.
 long-description: >
  Kubernetes resources and "records of intent" are all stored as API objects, and modified via RESTful calls to the API.
  The API allows configuration to be managed in a declarative way.
  Users can interact with the Kubernetes API directly, or via tools like `kubectl`.
  The core Kubernetes API is flexible and can also be extended to support custom resources.
@@ -0,0 +1,8 @@
 id: maintainer
 name: Maintainer
 tags:
 - community
 short-description: |
  A highly experienced [contributor](#term-contributor), active in multiple areas of Kubernetes, who has cross-area ownership and write access to a project's GitHub repository.
 long-description: |
  Maintainers work holistically across the project to maintain its health and success and have made substantial contributions, both through code development and broader organizational efforts.
@@ -0,0 +1,10 @@
 id: member
 name: Member
 tags:
 - community
 short-description: |
  A continuously active [contributor](#term-contributor) in the K8s community.
 long-description: >
  Members can have issues and PRs assigned to them and participate in [special interest groups (SIGs)](#term-sig) through GitHub teams.
  Pre-submit tests are automatically run for members' PRs.
  A member is expected to remain an active contributor to the community.
@@ -0,0 +1,9 @@
 id: minikube
 name: Minikube
 tags:
 - fundamental
 - tool
 short-description: |
  A tool for running Kubernetes locally.
 long-description: |
  Minikube runs a single-node cluster inside a VM on your computer.
@@ -0,0 +1,10 @@
 id: platform-developer
 name: Platform Developer
 aka:
  - Kubernetes Developer
 tags:
  - user-type
 short-description: |
  A person who customizes the Kubernetes platform to fit the needs of their project.
 long-description: >
  A platform developer may, for example, use [Custom Resources](/docs/concepts/api-extension/custom-resources/) or [Extend the Kubernetes API with the aggregation layer](/docs/concepts/api-extension/apiserver-aggregation/) to add functionality to their instance of Kubernetes, specifically for their application.
@@ -0,0 +1,16 @@
 id: pod
 name: Pod
 related:
 - container
 - sidecar
 - deployment
 - statefulset
 tags:
 - core-object
 - fundamental
 short-description: |
  The smallest and simplest Kubernetes object. A Pod represents a set of running [containers](#term-container) on your cluster.
 long-description: >
  A Pod is typically set up to run a single primary container.
  It can also run optional sidecar containers that add supplementary features like logging.
  Pods are commonly managed by a [Deployment](#term-deployment).
@@ -0,0 +1,9 @@
 id: rbac
 name: RBAC (Role-Based Access Control)
 tags:
 - security
 - fundamental
 short-description: |
  Manages authorization decisions, allowing admins to dynamically configure access policies through the [Kubernetes API](#term-kubernetes-api).
 long-description: |
  RBAC utilizes *roles*, which contain permission rules, and *role bindings*, which grant the permissions defined in a role to a set of users.
@@ -0,0 +1,8 @@
 id: reviewer
 name: Reviewer
 tags:
 - community
 short-description: |
  A person who reviews code for quality and correctness on some part of the project.
 long-description: |
  Reviewers are knowledgeable about both the codebase and software engineering principles. Reviewer status is scoped to a part of the codebase.
@@ -0,0 +1,9 @@
 id: service
 name: Service
 tags:
 - fundamental
 - core-object
 short-description: |
  An API object that describes how to access applications, such as a set of [Pods](#term-pod), and can describe ports and load-balancers.
 long-description: |
  The access point can be internal or external to the cluster.
@@ -0,0 +1,11 @@
 id: sig
 name: SIG (special interest group)
 tags:
 - community
 short-description: |
  [Members](#term-member) who collectively manage an ongoing piece or aspect of the larger Kubernetes open source project.
 long-description: >
  Members within a SIG have a shared interest in advancing a specific area, such as architecture, API machinery, or documentation.
  SIGs must follow the [SIG Governance](https://github.com/kubernetes/community/blob/master/sig-governance.md) guidelines but can have their own contribution policy and channels of communication.
  For more information, see the [kubernetes/community](https://github.com/kubernetes/community) repo and the current list of [SIGs and Working Groups](https://github.com/kubernetes/community/blob/master/sig-list.md).
@@ -1,18 +1,18 @@
 id: statefulset
 name: StatefulSet
-formerly:
+aka:
 - PetSet
 related:
- Deployment
+- deployment
- Pod
+- pod
 tags:
- Storage
+- core-object
- Workload
+- workload
- API Object
+- storage
 short-description: |
-  Manage the deployment and scaling of a set of Pods, *and provide guarantees about ordering*. They do so by maintaining a *unique*, sticky identity for each of their Pods.
+  Manages the deployment and scaling of a set of [Pods](#term-pod), *and provides guarantees about the ordering and uniqueness* of these Pods.
 long-description: |
-  Like Deployments, StatefulSets manage Pods that are based on an identical container spec. However, although their specs are the same, the Pods in a StatefulSet are not interchangeable. Each Pod has a persistent identifier that it maintains across any rescheduling.
+  Like a [Deployment](#term-deployment), a StatefulSet manages Pods that are based on an identical container spec. Unlike a Deployment, a StatefulSet maintains a sticky identity for each of their Pods. These pods are created from the same spec, but are not interchangeable&#58; each has a persistent identifier that it maintains across any rescheduling.
-  StatefulSets also operate according to the Controller pattern. You define your desired state in a StatefulSet *object*, and the StatefulSet *controller* makes any necessary updates to the get there from the current state.
+  A StatefulSet operates under the same pattern as any other Controller. You define your desired state in a StatefulSet *object*, and the StatefulSet *controller* makes any necessary updates to get there from the current state.
@@ -0,0 +1,11 @@
 id: upstream
 name: Upstream (disambiguation)
 related:
 - downstream
 tags:
 - community
 short-description: |
  May refer to: core Kubernetes or the source repo from which a repo was forked.
 long-description: |
  * In the **Kubernetes Community**: Conversations often use *upstream* to mean the core Kubernetes codebase, which the general ecosystem, other code, or third-party tools relies upon. For example, [community members](#term-member) may suggest that a feature is moved upstream so that it is in the core codebase instead of in a plugin or third-party tool.
  * In **GitHub** or **git**: The convention is to refer to a source repo as *upstream*, whereas the forked repo is considered *downstream*.
@@ -0,0 +1,10 @@
 id: wg
 name: WG (working group)
 tags:
 - community
 short-description: |
  Facilitates the discussion and/or implementation of a short-lived, narrow, or decoupled project for a committee, [SIG](#term-sig), or cross-SIG effort.
 long-description: |
  Working groups are a way of organizing people to accomplish a discrete task, and are relatively easy to create and deprecate when inactive.
  For more information, see the [kubernetes/community](https://github.com/kubernetes/community) repo and the current list of [SIGs and working groups](https://github.com/kubernetes/community/blob/master/sig-list.md).
@@ -2,6 +2,7 @@ bigheader: "Reference Documentation"
 abstract: "Design docs, concept definitions, and references for APIs and CLIs."
 toc:
 - docs/reference/index.md
 - docs/reference/glossary.md
 - title: Using the API
  section:
@@ -108,5 +109,3 @@ toc:
  - title: Kubernetes Issue Tracker on GitHub
    path: https://github.com/kubernetes/kubernetes/issues/
  - docs/reference/security.md
@@ -2,17 +2,19 @@
 To write a glossary snippet, start with a copy of the template, [`/_data/glossary/_example.yml`](/_data/glossary/_example.yml). Make sure to provide (or omit) values for the following fields:
-* (Required) `id`.
+* (Required) `id`
  * This field must match the name of the glossary file itself (without the `*.yml` extension). It is *not* intended to be displayed to users, and is only used programmatically.
-* (Required) `name`.
+* (Required) `name`
  * The name of the term.
-* (Required) `tags`.
+* (Required) `tags`
  * Must be one of the tags listed in kubernetes.github.io/_data/canonical-terms-tags.yml.
-* (Required) `short description`.
+* (Required) `short description`
  * Make sure to replace the instructional text in the template with your content.
-* (Optional) `formerly` and `related`.
+* (Optional) `aka`
-  * If you do not provide these values, remove the fields.
+  * These synonyms do not need to be glossary terms themselves (if they are deprecated), and can include spaces.
-* (Optional) `long description`.
+* (Optional) `related`
  * These should be the `id`s (not the `names`) of related glossary terms.
 * (Optional) `long description`
  * If you do not provide a long description, remove the field -- that is, the complete key-value pair.
 The `_example.yml` template also contains basic information about how to write your snippet. For additional guidance, continue reading this readme.
@@ -67,7 +67,9 @@
        </script>
        <a href="" onclick="window.open('https://github.com/kubernetes/kubernetes.github.io/issues/new?title=Issue%20with%20' +
        'k8s.io'+window.location.pathname)" class="button issue">Create an Issue</a>
-        <a href="/editdocs#{{ page.path }}" class="button issue">Edit this Page</a>
+        {% unless page.noedit %}
          <a href="/editdocs#{{ page.path }}" class="button issue">Edit this Page</a>
        {% endunless %}
    {% endif %}
    </div>
 </section>
@@ -0,0 +1,64 @@
 .preview-text p {
  display: inline;
 }
 .no-underline {
  text-decoration: none !important;
 }
 .hide {
  display: none !important;
 }
 .permalink {
  background-image: url(../images/link.png);
  background-repeat: no-repeat;
  display: inline-block;
  color: transparent;
  width: 20px;
  margin-left: 10px;
 }
 .term-anchor {
  display: block;
  position: relative;
  top: -90px;
  visibility: hidden;
 }
 .tag-option {
  padding: 5px;
  margin: 10px;
  float:left;
 }
 .canonical-tag {
  color: white;
  background-color: #b7c8e8;
 }
 .canonical-tag a {
  color: inherit;
  text-decoration: none !important;
 }
 .active-tag {
  background-color: #3371e3;
 }
 .invisible {
  visibility: hidden;
 }
 #tag-container {
  float: left;
  border-top: 1px solid #8c8c8c;
  border-bottom: 1px solid #8c8c8c;
  padding: 7px 0px;
  margin: 25px 0px;
 }
 .tag-description {
  text-align: center;
  margin: 5px 0px;
 }
@@ -0,0 +1,66 @@
 ---
 approvers:
 - chenopis
 - abiogenesis-now
 title: Standardized Glossary
 noedit: true
 default_active_tag: fundamental
 ---
 <link href="/css/glossary.css" rel="stylesheet">
 <script src="/js/glossary.js"></script>
 <p>This glossary is intended to be a comprehensive, standardized list of Kubernetes terminology. It includes technical terms that are specific to K8s, as well as more general terms that provide useful context.</p>
 <div id="tag-container">
 <p>Filter terms according to their tags:</p>
 <div class="tag-description invisible" id="placeholder">.</div>
 {% for tag in site.data.canonical-tags %}
 {% assign tag_info = tag[1] %}
 <div class="tag-description hide" id="{{ tag_info.id | prepend: "tag-" | append: "-description" }}">
 <i>{{ tag_info.description }}</i>
 </div>
 {% endfor %}
 {% assign sorted_tags = site.data.canonical-tags | where_exp: "tag", "true" | sort: 'name' %}
 {% for tag_info in sorted_tags %}
 {% assign tag_state_class = "" %}
 {% assign fullTagName = tag_info.id | prepend: "tag-" %}
 <span id="{{ fullTagName }}" class="tag-option canonical-tag {{ tag_state_class }}" data-target="{{ fullTagName }}">
 <a href="javascript:void(0)">{{ tag_info.name }}</a>
 </span>
 {% endfor %}
 <span class="tag-option"><a id="select-all-tags" href="javascript:void(0)">Select all</a></span>
 <span class="tag-option"><a id="deselect-all-tags" href="javascript:void(0)">Deselect all</a></span>
 </div>
 <p>Click on the <a href="javascript:void(0)" class="no-underline">[+]</a> indicators below to get a longer explanation for any particular term.</p>
 {% assign glossary_terms = site.data.glossary | where_exp: "term", "term.id != '_example'" | sort: 'name' %}
 <ul>
 {% for term in glossary_terms %}
 {% assign tag_classes = term.tags | join: " tag-" | prepend: "tag-" %}
 {% assign term_visibility_class = "hide" %}
 {% assign show_count = 0 %}
 {% assign term_identifier = term.id | prepend: 'term-' %}
 <li class="{{ tag_classes }} {{ term_visibility_class }}" data-show-count="{{ show_count }}">
 <div id="{{ term_identifier }}" class="term-anchor"></div>
 <div>
 <div class="term-name"><b>{{ term.name }}</b><a href="{{ term_identifier | prepend: '#' }}" class="permalink hide">LINK</a></div>
 {% if term.aka %}
 Also known as: <i>{{ term.aka | join: ", " }}</i>
 <br>
 {% endif %}
 <span class="preview-text">{{ term.short-description | markdownify }} <a href="javascript:void(0)" class="click-controller no-underline" data-target="{{ term.id }}">[+]</a></span>
 <div id="{{ term.id }}" class="hide">
 {{ term.long-description | markdownify }}
 </div>
 </div>
 </li>
 {% endfor %}
 </ul>
@@ -0,0 +1,181 @@
 // TODO (long-term): Would be easier to manage all this state with React
 $( document ).ready(function() {
  var expandText = "[+]";
  var closeText = "[-]";
  var selectAllKey = "all";
  var deselectAllKey = "none";
  var defaultActiveTag = "fundamental";
  var activeTags = {};
  var paramSize = function(paramHash) {
    return Object.keys(paramHash).length;
  }
  // "Lib" for acquiring parameters from the URL
  var urlParamLib = function() {
    function initParams() {
      var sPageURL = decodeURIComponent(window.location.search.substring(1)),
        sURLVariables = sPageURL.split('&'),
        sParameterName,
        i;
      var paramHash = {};
      for (i = 0; i < sURLVariables.length; i++) {
        sParameterName = sURLVariables[i].split('=');
        if (sParameterName[0] != "")
          paramHash[sParameterName[0]] = sParameterName[1];
      }
      if (paramSize(paramHash) == 0) {
        paramHash[defaultActiveTag] = true;
      }
      return paramHash;
    }
    function updateParams(paramHash) {
      var urlWithoutQuery = window.location.href.split('?')[0];
      var urlHash = window.location.hash;
      window.history.pushState(null,null, urlWithoutQuery + "?" + $.param(paramHash) + window.location.hash);
    }
    return {
      initParams: initParams,
      updateParams: updateParams,
    };
  }();
  var initClickFunctions = function() {
    var deactivateTagTerms = function(elt) {
      var targetTag = elt.data("target");
      var targetClass = "." + targetTag;
      var tagName = targetTag.split('tag-')[1];
      elt.removeClass("active-tag");
      $(targetClass).each(function(){
        var showCount = $(this).data("show-count");
        var newShowCount = showCount - 1;
        $(this).data("show-count", newShowCount);
        if (newShowCount < 1) {
          $(this).addClass("hide");
        }
      });
      delete activeTags[tagName];
    };
    var activateTagTerms = function(elt) {
      var targetTag = elt.data("target");
      var targetClass = "." + targetTag;
      var tagName = targetTag.split('tag-')[1];
      elt.addClass("active-tag");
      $(targetClass).each(function(){
        var showCount = $(this).data("show-count");
        var newShowCount = showCount + 1;
        $(this).data("show-count", newShowCount);
        if (newShowCount > 0) {
          $(this).removeClass("hide");
        }
      });
      activeTags[tagName] = true;
      if (activeTags[deselectAllKey]) {
        delete activeTags[deselectAllKey];
      }
    };
    // Shows/hides glossary terms when their relevant tags are clicked
    $(".canonical-tag").each(function(){
      var placeholder = $("#placeholder");
      var targetTag = $(this).data("target");
      $(this).mouseenter(function(){
        var tagDescription = $("#" + targetTag + "-description").html();
        placeholder.html(tagDescription);
        placeholder.removeClass('invisible');
      }).mouseleave(function(){
        placeholder.addClass('invisible');
      });
      $(this).click(function(){
        var shouldHide = $(this).hasClass("active-tag");
        if (shouldHide) {
          deactivateTagTerms($(this));
        } else {
          activateTagTerms($(this));
        }
        urlParamLib.updateParams(activeTags);
      });
    });
    // Adds functionality to "select all tags" link
    $("#select-all-tags").click(function(){
      $(".canonical-tag").each(function(){
        var shouldActivate = !$(this).hasClass("active-tag");
        if (shouldActivate) {
          activateTagTerms($(this));
        }
      });
      queryParams = {}
      queryParams[selectAllKey] = true;
      urlParamLib.updateParams(queryParams);
    });
    // Adds functionality to "deselect all tags" link
    $("#deselect-all-tags").click(function(){
      $(".canonical-tag").each(function(){
        var shouldHide = $(this).hasClass("active-tag");
        if (shouldHide) {
          deactivateTagTerms($(this));
        }
      });
      queryParams = {}
      queryParams[deselectAllKey] = true;
      urlParamLib.updateParams(queryParams);
    });
    // Expands/hides glossary term definitions when [+] button is clicked
    $(".click-controller").each(function(){
      $(this).click(function() {
        var targetId = $(this).data("target");
        var shouldExpand = $(this).html() == expandText;
        if (shouldExpand) {
          $("#" + targetId).removeClass('hide');
          $(this).html(closeText);
        } else {
          $("#" + targetId).addClass('hide');
          $(this).html(expandText);
        }
      });
    });
    // Shows permalink when term name is hovered over
    $(".term-name").each(function() {
      var permalink = $($(this).parent().find(".permalink")[0]);
      $(this).mouseenter(function(){
        permalink.removeClass("hide");
      }).mouseleave(function(){
        permalink.addClass("hide");
      });;
    });
  };
  function initActiveTags() {
    if (activeTags[selectAllKey]) {
      $("#select-all-tags").click();
    } else if (activeTags[deselectAllKey]) {
      $("#deselect-all-tags").click();
    } else {
      for (var tagId in activeTags) {
        $("#tag-" + tagId).find("a")[0].click();
      }
    }
  }
  initClickFunctions();
  activeTags = urlParamLib.initParams();
  initActiveTags();
 });
@@ -29,41 +29,53 @@ import (
 type GlossaryTerm struct {
  Id string          `yaml: "id"`
  Name string        `yaml: "name"`
-  Formerly []string  `yaml: "formerly"`
+  Aka []string       `yaml: "aka"`
  Related []string   `yaml: "related"`
  Tags []string      `yaml: "tags"`
 }
 // Not unmarshaling other fields (for simplicity)
 type CanonicalTag struct {
  Id string          `yaml: "id"`
 }
 // Checks that all glossary files (../_data/glossary/*) contain valid tags
 // that are present in the canonical set.
 func TestCanonicalTags(t *testing.T) {
-  canonicalTagsFile := "../_data/canonical-tags.yml"
+  canonicalTagsDir := "../_data/canonical-tags"
-  data, err := ioutil.ReadFile(canonicalTagsFile)
+  files, err := ioutil.ReadDir(canonicalTagsDir)
  if err != nil {
-    t.Errorf("Unable to read file %s: %v", canonicalTagsFile, err)
+    t.Errorf("Unable to read directory %s: %v", canonicalTagsDir, err)
    return
  }
  var tagList []string
  err = yaml.Unmarshal(data, &tagList)
  if err != nil {
    t.Errorf("Unable to unmarshal file %s: %v", tagList, err)
    return
  }
  canonicalTagsSet := make(map[string]bool)
-  for _, tag := range tagList {
+  var tag CanonicalTag
-    canonicalTagsSet[tag] = true
+  for _, f := range files {
    filePath := path.Join(canonicalTagsDir, f.Name())
    data, err := ioutil.ReadFile(filePath)
    if err != nil {
      t.Errorf("Unable to read file %s: %v", filePath, err)
      continue
    }
    err = yaml.Unmarshal(data, &tag)
    if err != nil {
      t.Errorf("Unable to unmarshal file %s: %v", filePath, err)
      continue
    }
    canonicalTagsSet[tag.Id] = true
  }
  glossaryDir := "../_data/glossary"
-  files, err := ioutil.ReadDir(glossaryDir)
+  files, err = ioutil.ReadDir(glossaryDir)
  if err != nil {
    t.Errorf("Unable to read directory %s: %v", glossaryDir, err)
    return
  }
  var term GlossaryTerm
  for _, f := range files {
    var term GlossaryTerm
    // skip validation of example files
    if (strings.HasPrefix(f.Name(), "_")) {
      continue
@@ -81,9 +93,12 @@ func TestCanonicalTags(t *testing.T) {
      continue
    }
    if (len(term.Tags) == 0) {
      t.Errorf("Glossary term \"%s\" requires at least one tag. See %s for the list of valid tags.", term.Name, canonicalTagsDir)
    }
    for _, tag := range term.Tags {
      if _, present := canonicalTagsSet[tag]; !present {
-        t.Errorf("Glossary term \"%s\" has invalid tag \"%s\". See %s for the list of valid tags.", term.Name, tag, canonicalTagsFile)
+        t.Errorf("Glossary term \"%s\" has invalid tag \"%s\". See %s for the list of valid tags.", term.Name, tag, canonicalTagsDir)
        continue
      }
    }