ref(*): misc code, comment, docs updates around claims

Signed-off-by: Vaughn Dice <vadice@microsoft.com>

docs/content/docker-images/client.md

@@ -13,12 +13,13 @@ It has tags that match what is available from our [install](/install/) page:
 
 * The Docker socket must be mounted to the container in order to execute a
   bundle, using `-v /var/run/docker.sock:/var/run/docker.sock`.
-* The `ENTRYPOINT` is set to `porter`, to change that you can use 
-  `--entrypoint`, for example `docker run --rm -it --entrypoint /bin/sh porter`. 
+* The `ENTRYPOINT` is set to `porter`. To change this, you can use
+  `--entrypoint`, e.g. `docker run --rm -it --entrypoint /bin/sh porter`.
 * Don't mount the entire Porter home directory, because that's where the porter
-  binary is located, instead mount individual directories such as claims or
-  credentials underneath it. Otherwise you will get an error like 
-  `exec user process caused "exec format error"`.
+  binary is located, instead mount individual directories such as claims,
+  results and outputs (all three are used to record data for an installation)
+  or credentials and parameters, if needed. Otherwise you will get an error
+  like `exec user process caused "exec format error"`.
 
 ## Examples
 Here are some examples of how to use the Porter client Docker image.
@@ -64,6 +65,8 @@ Finally let's install a bundle:
 $ docker run -it --rm \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v $HOME/.porter/claims:/root/.porter/claims \
+    -v $HOME/.porter/results:/root/.porter/results \
+    -v $HOME/.porter/outputs:/root/.porter/outputs \
     getporter/porter install -t getporter/porter-hello:0.1.0
 
 installing hello...
@@ -80,6 +83,8 @@ We can also list our installed bundles with their status:
 $ docker run -it --rm \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v $HOME/.porter/claims:/root/.porter/claims \
+    -v $HOME/.porter/results:/root/.porter/results \
+    -v $HOME/.porter/outputs:/root/.porter/outputs \
     getporter/porter list
 
 NAME      CREATED         MODIFIED        LAST ACTION   LAST STATUS

docs/content/mixins-vs-plugins.md

@@ -19,9 +19,9 @@ imagination.
 
 [Plugins](/plugins/) **extend** the Porter client itself, **reimplementing**
 Porter's default functionality. There are fixed extension points in Porter with
-a defined interface. For example, Porter saves claims and credential sets using the local
-filesystem to ~/.porter by default. A plugin can change that behavior to save
-them to cloud storage instead.
+a defined interface. For example, Porter saves installation data, credential
+sets and parameter sets using the local filesystem to ~/.porter by default. A
+plugin can change that behavior to save them to cloud storage instead.
 
 What both mixins and plugins have in common is that anyone can create their own
 and distribute them, just like the ones that we install with Porter by default.

docs/content/plugins/_index.md

@@ -5,9 +5,9 @@ description: Learn what a Porter plugin can do and see a listing of available pl
 
 The Porter client is extensible and anyone can write a plugin to integrate with
 Porter. Plugins extend the Porter client, reimplementing Porter's default
-functionality. For example, Porter saves claims and credential sets using the local
-filesystem to ~/.porter by default. A plugin can change that behavior to save
-them to cloud storage instead. 
+functionality. For example, Porter saves installation data, credential sets and
+parameter sets using the local filesystem to ~/.porter by default. A plugin can
+change that behavior to save them to cloud storage instead.
 
 [Plugins are very different from mixins][vs], which give you building blocks for
 authoring bundles. There are a couple [types of plugins][types] and a single

docs/content/plugins/azure.md

@@ -19,7 +19,8 @@ porter plugin install azure
 
 ### Storage
 
-Storage plugins allow Porter to store data, such as claims and credentials, in Azure cloud.
+Storage plugins allow Porter to store data, such as installation data and
+credentials or parameters, in Azure cloud.
 
 #### Blob
 

docs/content/plugins/types/_index.md

@@ -11,9 +11,10 @@ switched by editing Porter's [configuration file](/configuration/).
 
 Storage plugins let you persist files created by Porter to an alternative
 location, instead of to the local filesystem under ~/.porter. By default,
-credential sets (created by `porter credentials generate`) are saved to
-~/.porter/credentials and records of a bundle being executed (claims) are saved
-to ~/.porter/claims.
+credential and parameter sets are saved to the /credentials and /parameters
+directories under ~/.porter and installation records of a bundle being
+executed, including claim receipts, action results and outputs, are saved to
+the /claims, /results and /outputs directories under ~/.porter.
 
 A storage plugin can implement the [crud.Store interface][crudstore] and change
 where those files are saved. For example, the [Azure plugin](/plugins/azure/)

pkg/cnab/provider/parameters_test.go

@@ -56,8 +56,8 @@ func Test_loadParameters_definitionNotDefined(t *testing.T) {
 func Test_loadParameters_applyTo(t *testing.T) {
 	r := NewTestRuntime(t)
 
-	// Here we set default values, but we expect the corresponding
-	// claim values to take precedence when loadParameters is called
+	// Here we set default values, but expect nil/empty
+	// values for parameters that do not apply to a given action
 	b := bundle.Bundle{
 		Definitions: definition.Definitions{
 			"foo": &definition.Schema{

pkg/config/config.go

@@ -19,10 +19,10 @@ const (
 	// EnvBundleName is the name of the environment variable containing the name of the bundle.
 	EnvBundleName = "CNAB_BUNDLE_NAME"
 
-	// EnvClaimName is the name of the environment variable containing the name of the claim.
-	EnvClaimName = "CNAB_INSTALLATION_NAME"
+	// EnvInstallationName is the name of the environment variable containing the name of the installation.
+	EnvInstallationName = "CNAB_INSTALLATION_NAME"
 
-	// EnvACTION is the request
+	// EnvACTION is the requested action to be executed
 	EnvACTION = "CNAB_ACTION"
 
 	// EnvDEBUG is a custom porter parameter that signals that --debug flag has been passed through from the client to the runtime.

pkg/porter/cnab.go

@@ -112,7 +112,7 @@ func (o *sharedOptions) Validate(args []string, p *Porter) error {
 	return nil
 }
 
-// validateInstallationName grabs the claim name from the first positional argument.
+// validateInstallationName grabs the installation name from the first positional argument.
 func (o *sharedOptions) validateInstallationName(args []string) error {
 	if len(args) == 1 {
 		o.Name = args[0]

pkg/porter/lifecycle_test.go

@@ -125,7 +125,7 @@ func TestBundleLifecycleOpts_ToActionArgs(t *testing.T) {
 					RelocationMapping: "relocation-mapping.json",
 					File:              config.Name,
 				},
-				Name: "MyClaim",
+				Name: "MyInstallation",
 				Params: []string{
 					"PARAM1=VALUE1",
 				},
@@ -155,7 +155,7 @@ func TestBundleLifecycleOpts_ToActionArgs(t *testing.T) {
 		assert.Equal(t, opts.CredentialIdentifiers, args.CredentialIdentifiers, "CredentialIdentifiers not populated correctly")
 		assert.Equal(t, opts.Driver, args.Driver, "Driver not populated correctly")
 		assert.Equal(t, expectedParams, args.Params, "Params not populated correctly")
-		assert.Equal(t, opts.Name, args.Installation, "Claim not populated correctly")
+		assert.Equal(t, opts.Name, args.Installation, "Installation not populated correctly")
 		assert.Equal(t, opts.RelocationMapping, args.RelocationMapping, "RelocationMapping not populated correctly")
 	})
 }

pkg/porter/list.go

@@ -17,7 +17,8 @@ type ListOptions struct {
 	printer.PrintOptions
 }
 
-// DisplayInstallation holds a subset of pertinent values to be listed from a claim.Claim
+// DisplayInstallation holds a subset of pertinent values to be listed from installation data
+// originating from its claims, results and outputs records
 type DisplayInstallation struct {
 	Name     string
 	Created  time.Time

pkg/porter/options.go

@@ -22,7 +22,7 @@ func (p *Porter) applyDefaultOptions(opts *sharedOptions) error {
 	}
 
 	//
-	// Default the claim name to the bundle name
+	// Default the installation name to the bundle name
 	//
 	if opts.Name == "" {
 		opts.Name = p.Manifest.Name

pkg/porter/outputs.go

@@ -35,7 +35,7 @@ func (o *OutputShowOptions) Validate(args []string, cxt *context.Context) error
 		return errors.Errorf("only one positional argument may be specified, the output name, but multiple were received: %s", args)
 	}
 
-	// If not provided, attempt to derive claim name from context
+	// If not provided, attempt to derive installation name from context
 	if o.sharedOptions.Name == "" {
 		err := o.sharedOptions.defaultBundleFiles(cxt)
 		if err != nil {
@@ -49,13 +49,13 @@ func (o *OutputShowOptions) Validate(args []string, cxt *context.Context) error
 // Validate validates the provided args, using the provided context,
 // setting attributes of OutputListOptions as applicable
 func (o *OutputListOptions) Validate(args []string, cxt *context.Context) error {
-	// Ensure only one argument exists (claim name) if args length non-zero
+	// Ensure only one argument exists (installation name) if args length non-zero
 	err := o.sharedOptions.validateInstallationName(args)
 	if err != nil {
 		return err
 	}
 
-	// Attempt to derive claim name from context
+	// Attempt to derive installation name from context
 	err = o.sharedOptions.defaultBundleFiles(cxt)
 	if err != nil {
 		return errors.Wrap(err, "installation name must be provided")
@@ -129,8 +129,8 @@ func NewDisplayOutputs(outputs claim.Outputs, format printer.Format) DisplayOutp
 	return displayOutputs
 }
 
-// ListBundleOutputs lists the outputs for a given bundle,
-// according to the provided claim and display format
+// ListBundleOutputs lists the outputs for a given bundle according to the
+// provided display format
 func (p *Porter) ListBundleOutputs(opts *OutputListOptions) (DisplayOutputs, error) {
 	err := p.applyDefaultOptions(&opts.sharedOptions)
 	if err != nil {

pkg/porter/show.go

@@ -9,7 +9,7 @@ import (
 	dtprinter "github.com/carolynvs/datetime-printer"
 )
 
-// ShowOptions represent options for showing a particular claim
+// ShowOptions represent options for showing a particular installation
 type ShowOptions struct {
 	sharedOptions
 	printer.PrintOptions
@@ -31,7 +31,7 @@ func (so *ShowOptions) Validate(args []string, cxt *context.Context) error {
 	return so.ParseFormat()
 }
 
-// ShowInstallation shows a bundle, or more properly a bundle claim, along with any
+// ShowInstallation shows a bundle installation, along with any
 // associated outputs
 func (p *Porter) ShowInstallation(opts ShowOptions) error {
 	err := p.applyDefaultOptions(&opts.sharedOptions)
@@ -69,7 +69,7 @@ func (p *Porter) ShowInstallation(opts ShowOptions) error {
 			Now: func() time.Time { return now },
 		}
 
-		// Print claim details
+		// Print installation details
 		fmt.Fprintf(p.Out, "Name: %s\n", displayInstallation.Name)
 		fmt.Fprintf(p.Out, "Created: %s\n", tp.Format(displayInstallation.Created))
 		fmt.Fprintf(p.Out, "Modified: %s\n", tp.Format(displayInstallation.Modified))

pkg/runtime/runtime.go

@@ -34,9 +34,9 @@ func NewPorterRuntime(cxt *context.Context, mixins pkgmgmt.PackageManager) *Port
 func (r *PorterRuntime) Execute(rm *RuntimeManifest) error {
 	r.RuntimeManifest = rm
 
-	claimName := os.Getenv(config.EnvClaimName)
+	installationName := os.Getenv(config.EnvInstallationName)
 	bundleName := os.Getenv(config.EnvBundleName)
-	fmt.Fprintf(r.Out, "executing %s action from %s (installation: %s)\n", r.RuntimeManifest.Action, bundleName, claimName)
+	fmt.Fprintf(r.Out, "executing %s action from %s (installation: %s)\n", r.RuntimeManifest.Action, bundleName, installationName)
 
 	err := r.RuntimeManifest.Validate()
 	if err != nil {