From c0524b3c472b5c0681c0cd222efee795a7ebe42b Mon Sep 17 00:00:00 2001
From: Josh Matthews <josh@joshmatthews.net>
Date: Mon, 18 Apr 2016 12:42:33 -0400
Subject: [PATCH 1/2] Start collecting documentation, and add an in-tree
 glossary. Encourage new contributors to add missing entries as appropriate.

---
 CONTRIBUTING.md                               | 10 +++----
 README.md                                     |  2 +-
 .../HACKING_QUICKSTART.md                     |  0
 ORGANIZATION.md => docs/ORGANIZATION.md       |  0
 docs/glossary.md                              | 27 +++++++++++++++++++
 5 files changed, 33 insertions(+), 6 deletions(-)
 rename HACKING_QUICKSTART.md => docs/HACKING_QUICKSTART.md (100%)
 rename ORGANIZATION.md => docs/ORGANIZATION.md (100%)
 create mode 100644 docs/glossary.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b37152767de..bc3240c7d1a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,9 +17,12 @@ the GitHub issue that you want to work on it. This is to prevent duplicated
 efforts from contributors on the same issue.
 
 Head over to [Servo Starters](http://servo.github.io/servo-starters/) to find
-good tasks to start with.
+good tasks to start with. If you come across words or jargon that do not make
+sense, please check [the glossary](docs/glossary.md) first. If there's no
+matching entry, please make a pull request to add one with the content `TODO`
+so we can correct that!
 
-See [`HACKING_QUICKSTART.md`](HACKING_QUICKSTART.md) for more information
+See [`HACKING_QUICKSTART.md`](docs/HACKING_QUICKSTART.md) for more information
 on how to start working on Servo.
 
 ## Pull Request Checklist
@@ -31,9 +34,6 @@ on how to start working on Servo.
 - Commits should be as small as possible, while ensuring that each commit is
   correct independently (i.e., each commit should compile and pass tests). 
 
-- Don't put submodule updates in your pull request unless they are to landed
-  commits.
-
 - If your patch is not getting reviewed or you need a specific person to review
   it, you can @-reply a reviewer asking for a review in the pull request or a
   comment, or you can ask for a review in `#servo` on `irc.mozilla.org`.
diff --git a/README.md b/README.md
index 8fb76654b76..a51eb95d171 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ Servo is a prototype web browser engine written in the
 64bit OS X, 64bit Linux, Android, and Gonk (Firefox OS).
 
 Servo welcomes contribution from everyone.  See
-[`CONTRIBUTING.md`](CONTRIBUTING.md) and [`HACKING_QUICKSTART.md`](HACKING_QUICKSTART.md)
+[`CONTRIBUTING.md`](CONTRIBUTING.md) and [`HACKING_QUICKSTART.md`](docs/HACKING_QUICKSTART.md)
 for help getting started.
 
 Visit the [Servo Project page](https://servo.org/) for news and guides.
diff --git a/HACKING_QUICKSTART.md b/docs/HACKING_QUICKSTART.md
similarity index 100%
rename from HACKING_QUICKSTART.md
rename to docs/HACKING_QUICKSTART.md
diff --git a/ORGANIZATION.md b/docs/ORGANIZATION.md
similarity index 100%
rename from ORGANIZATION.md
rename to docs/ORGANIZATION.md
diff --git a/docs/glossary.md b/docs/glossary.md
new file mode 100644
index 00000000000..4d4ac9ea585
--- /dev/null
+++ b/docs/glossary.md
@@ -0,0 +1,27 @@
+### Compositor ###
+    
+The thread that receives input events from the operating system and forwards them to the constellation. It is also in charge of compositing complete renders of web content and displaying them on the screen as fast as possible.
+
+### Constellation ###
+
+The thread that controls a collection of related web content. This could be thought of as an owner of a single tab in a tabbed web browser; it encapsulates session history, knows about all frames in a frame tree, and is the owner of the pipeline for each contained frame.
+
+### Display list ###
+
+TODO
+
+### Layout thread ###
+
+A thread that is responsible for laying out a DOM tree into layers of boxes for a particular document. Receives commands from the script thread to lay out a page and either generate a new display list for use by the renderer thread, or return the results of querying the layout of the page for use by script.
+
+### Pipeline ###
+
+A unit encapsulating a means of communication with the script, layout, and renderer threads for a particular document. Each pipeline has a globally-unique id which can be used to access it from the constellation.
+
+### Script thread (alt. script task) ###
+
+A thread that executes JavaScript and stores the DOM representation of all documents that share a common [origin](https://tools.ietf.org/html/rfc6454). This thread translates input events received from the constellation into DOM events [per the specification](https://w3c.github.io/uievents/), invokes the HTML parser when new page content is received, and evaluates JS for events like timers and `<script>` elements.
+
+### Renderer thread (alt. paint thread) ###
+
+A thread which translates a display list into a series of drawing commands that render the contents of the associated document into a buffer, which is then sent to the compositor.

From f78ff93b5f09a4387c702ea9f83da5c4dbcea8ac Mon Sep 17 00:00:00 2001
From: Josh Matthews <josh@joshmatthews.net>
Date: Mon, 18 Apr 2016 12:49:34 -0400
Subject: [PATCH 2/2] Add instructions to glossary.

---
 docs/glossary.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/docs/glossary.md b/docs/glossary.md
index 4d4ac9ea585..32e907823d0 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -1,3 +1,11 @@
+# How to use this glossary
+
+This is a collection of common terms that have a specific meaning in the context of the Servo project. The goal is to provide high-level definitions and useful links for further reading, rather than complete documentation about particular parts of the code.
+
+If there is a word or phrase used in Servo's code, issue tracker, mailing list, etc. that is confusing, please make a pull request that adds it to this file with a body of `TODO`. This will signal more knowledgeable people to add a more meaningful definition.
+
+# Glossary
+
 ### Compositor ###
     
 The thread that receives input events from the operating system and forwards them to the constellation. It is also in charge of compositing complete renders of web content and displaying them on the screen as fast as possible.