Update Reproduciblity Readme (#423)

Author: gfs

src/oss-reproducible/README.md

@@ -1,32 +1,41 @@
 # OSS Reproducible
 
-The purpose of *oss-reproducible* is to analyze open source packages for reproducibility. We start with
+The purpose of *oss-reproducible* is to analyze open source packages for `semantic reproducibility`. We start with
 an existing package (for example, the NPM "left-pad" package, version 1.3.0), and we try to answer the
-question, **Do the package contents authentically reflect the purported source code?**
+question, **How accurately does the source code represent the published package?**
 
 ## Why Reproducibility?
+Reproducible builds allow confidence that packages are derived from the source code that produced them.
+
+## Semantic Reproducibility
+A project build is `semantically reproducible` if its build results can be either recreated exactly (a bit for bit [reproducible build](https://en.wikipedia.org/wiki/Reproducible_builds)), or if the differences between the release package and a rebuilt package are not expected to produce functional differences in normal cases.
+
+For example, the rebuilt package might have different date/time stamps, or one might include files like .gitignore that are not in the other and would not change the execution of a program under normal circumstances.
 
 ## How It Works
 
 We start by downloading the package from the respective package repository, using OSS Download. Then
 we look for the source (using OSS Find Source) and try to find and download the correct version of it.
 
-OSS Reproducible uses "strategies" to try to correlate source code with the package contents. These
+OSS Reproducible uses `strategies` to try to correlate source code with the package contents. These
 strategies include:
 
-* PackageMatchesSourceStrategy: Do the package contents exactly match the source code repository
+* `PackageMatchesSourceStrategy`: Do the package contents exactly match the source code repository
   contents?
-* PackageContainedInSourceStragegy: Does every file in the package exist in the source code repository?
+* `PackageContainedInSourceStragegy`: Does every file in the package exist in the source code repository?
   Note that this is different from the previous strategy; for example, unit tests in the source repository
   that don't appear in the package would be fine for this strategy.
-* AutoBuildProducesSamePackage: Can we re-build the package from the source code repository? Since
+* `AutoBuildProducesSamePackage`: Can we re-build the package from the source code repository? Since
   there is a huge variety in build methods, this can very difficult, or in many cases, impossible.
-* OryxBuildStrategy: The Microsoft Oryx project has independent logic to attempt to "build" source
+* `OryxBuildStrategy`: The Microsoft Oryx project has independent logic to attempt to "build" source
   code repositories, so we leverage that as well.
 
+OSS Reproducible calculates an estimate of the similarity between the published package from OSS-Download
+and the associated source code from OSS-Find-Source.
+
 ## Ignoring Files
 
-Certain files are uninteresting from a reproducibility perspective, and are excluded from analyses.
+Certain files are uninteresting from a `semantic reproducibility` perspective and are excluded from analyses. 
 These files are defined in Strategies/PackageIgnoreList.txt.
 
 ## Contributing to OSS Reproducible

src/oss-reproducible/ReproducibleTool.cs

@@ -34,7 +34,7 @@ public static IEnumerable<Example> Examples
                 get
                 {
                     return new List<Example>() {
-                        new Example("Checks reproducibility of the given package",
+                        new Example("Estimate semantic reproducibility of the given package",
                             new Options { Targets = new List<string>() {"[options]", "package-url..." } })
                     };
                 }
@@ -105,7 +105,7 @@ public KeyValuePair<double, string> GetReproducibilityScore(ReproducibleToolResu
         {
             if (fullResult.Results == null)
             {
-                return KeyValuePair.Create(0.0, "No reproducibility results were created.");
+                return KeyValuePair.Create(0.0, "No semantic reproducibility results were created.");
             }
 
             KeyValuePair<double, string> bestScore = KeyValuePair.Create(0.0, "No strategies were able to successfully derive the package from the source code.");