From 711e89b9066a8da7baf41d4afc44e9071ee56ec3 Mon Sep 17 00:00:00 2001
From: Markus Schirp <mbj@schirp-dso.com>
Date: Tue, 20 Nov 2018 14:23:43 +0000
Subject: [PATCH] Add nomenclature section to readme

---
 README.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 79 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index dec62279..6e687fe2 100644
--- a/README.md
+++ b/README.md
@@ -17,15 +17,88 @@ Mutant supports ruby >= 2.5, MRI only.
 Mutant uses a pure Ruby [parser](https://github.com/whitequark/parser) and an [unparser](https://github.com/mbj/unparser)
 to do its magic.
 
-Installation
+Nomenclature
 ------------
 
-As mutant right now only supports rspec, install the gem `mutant-rspec` via your preferred method.
-It'll pull the `mutant` gem (in the correct version), that contains the main engine.
+The following explains several nouns you may experience in mutant's documentation.
+It's a good idea to familiarize yourself before moving on.
 
-```ruby
-gem install mutant-rspec
-```
+### AST
+
+Acronym for [Abstract Syntax Tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree)
+and the level of abstraction mutant operates on.
+
+### Subject
+
+An addressable piece of code to be targeted for mutation testing.
+
+Mutant currently supports the following subjects:
+
+* Instance methods
+* Singleton (class) methods
+
+Other subjects (constants, class bodies for DSLs, ...) are possible but aren't
+implemented in the OSS version.
+
+### Mutation operator
+
+A transformation applied to the AST of a subject. Mutant knows the following high level operator
+classes:
+
+* Semantic Reduction
+* Orthogonal Replacement
+* [Noop](#neutral-noop-tests)
+
+An exhaustive list can be found in the [mutant-meta](https://github.com/mbj/mutant/tree/master/meta)
+subdirectory of the source.
+
+### Mutation
+
+The result of applying a mutation operator to the AST of a subject. A mutation represents a
+hypothesis that ideally gets falsified by the tests.
+
+### Insertion
+
+The process of inserting a mutation into the runtime environment.
+Mutant currently supports insertion via dynamically created monkeypatches.
+
+Other insertion strategies (such as "boot time") are possible but aren't implemented
+in the OSS version.
+
+### Isolation
+
+The attempt to isolate the (side) effects of killing a mutation via an integration
+to prevent a mutation leaking into adjacent concurrent, or future mutations.
+
+Examples of sources for leaks are
+
+* Global variable writes
+* Thread local writes
+* DB State
+* File system
+
+Natively, mutant offers fork isolation. This works for any state within the executing
+Ruby process. For all state reachable via IO, it's the test author's responsibility to
+provide proper isolation.
+
+### Integration
+
+The method used to determine if a specific inserted mutation is covered by tests.
+
+Currently mutant supports integrations for:
+
+* rspec (https://rubygems.org/gems/mutant-rspec)
+* minitest (https://rubygems.org/gems/mutant-minitest)
+
+### Report
+
+Mutant currently provides two different reporters:
+
+* Progress (printed during mutation testing).
+* Summary (printed at the end of a finished analysis run)
+
+A reporter producing a machine readable report does not exist in the OSS version
+at the time of writing this documentation.
 
 Examples
 --------