Rewrite packages content and split into Config and Provider chapters (#…

…566)

Signed-off-by: Pete Lumbis <pete@upbound.io>

content/master/concepts/packages.md

@@ -8,8 +8,13 @@ A _Configuration_ package is an
 [OCI container images](https://opencontainers.org/) containing a collection of
 [Compositions]({{<ref "./compositions" >}}), 
 [Composite Resource Definitions]({{<ref "./composite-resource-definitions" >}})
+<<<<<<< HEAD
 and any required [Providers]({{<ref "./providers">}})
 representing a set of custom APIs and resources. 
+=======
+and any required [Providers]({{<ref "./providers">}}) or 
+[Functions]({{<ref "./composition-functions" >}}).
+>>>>>>> c0fd459 (Rewrite packages content and split into Config and Provider chapters (#566))
 
 Configuration packages make your Crossplane configuration fully portable. 
 
@@ -81,7 +86,7 @@ configuring the Crossplane Pod settings in the
 Provide the name of the Configuration's `.xpkg` file and set 
 {{<hover label="offline" line="7">}}packagePullPolicy: Never{{</hover>}}.
 
-For example, to install a locally downloaded version of 
+For example, to install a locally stored version of 
 Upbound AWS reference platform set the 
 {{<hover label="offline" line="6">}}package{{</hover>}} to the local filename
 and set the Configuration's
@@ -182,19 +187,21 @@ spec:
 # Removed for brevity
 ```
 
-#### Upgrade policy
+#### Revision activation policy
 
-Crossplane automatically upgrades a Configuration the to the latest version 
-available in the package cache. 
+The `Active` package revision
+is the package controller actively reconciling resources. 
+
+By default Crossplane sets the most recently installed package revision as 
+`Active`.
 
 Control the Configuration upgrade behavior with a
 {{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}}.
 
 The {{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}} 
 options are:
-* `Automatic` - (**default**) Automatically use the latest Configuration version
-  available in the cache. 
-* `Manual` - Require the current Configuration in use to be manually set. 
+* `Automatic` - (**default**) Automatically activate the last installed configuration.
+* `Manual` - Don't automatically activate a configuration. 
 
 For example, to change the upgrade behavior to require manual upgrades, set 
 {{<hover label="revision" line="6">}}revisionActivationPolicy: Manual{{</hover>}}.
@@ -209,16 +216,6 @@ spec:
 # Removed for brevity
 ```
 
-{{<hint "important" >}}
-Crossplane only upgrades a Configuration if a newer version is in the package 
-cache.   
-By default the Crossplane 
-[`packagePullPolicy`](#configuration-package-pull-policy) doesn't
-download new Configuration versions, even if they're available.
-{{< /hint >}}
-
-Read the [Configuration package revision](#configuration-revisions) 
-section for more information on the use of package revisions.
 
 #### Install a Configuration from a private registry
 
@@ -310,6 +307,8 @@ spec:
 Verify a Configuration with 
 {{<hover label="verify" line="1">}}kubectl get configuration{{</hover >}}.
 
+A working configuration reports `Installed` and `Healthy` as `True`.
+
 ```shell {label="verify",copy-lines="1"}
 kubectl get configuration
 NAME               INSTALLED   HEALTHY   PACKAGE                                           AGE
@@ -319,7 +318,7 @@ platform-ref-aws   True        True      xpkg.upbound.io/upbound/platform-ref-aw
 ### Manage dependencies
 
 Configuration packages may include dependencies on other packages including
-Providers or other Configurations. 
+Functions, Providers or other Configurations. 
 
 If Crossplane can't meet the dependencies of a Configuration the Configuration
 reports `HEALTHY` as `False`. 
@@ -386,7 +385,9 @@ for package requirements when building packages with third-party tools.
 A Configuration package requires a `crossplane.yaml` file and may include
 Composition and CompositeResourceDefinition files. 
 
+<!-- vale Google.Headings = NO -->
 ### The crossplane.yaml file
+<!-- vale Google.Headings = YES -->
 
 To build a Configuration package using the Crossplane CLI, create a file
 named 
@@ -446,7 +447,7 @@ include in the package.
 {{<hint "important" >}}
 You must ignore any other YAML files with `--ignore=<file_list>`.  
 For
-example, `crossplane build configuration -f test-directory --ignore=".tmp/*,other-file.yaml"`.
+example, `crossplane build configuration -f test-directory --ignore=".tmp/*"`.
 
 Including YAML files that aren't Compositions or CompositeResourceDefinitions, 
 including Claims isn't supported.

content/master/concepts/providers.md

@@ -122,7 +122,7 @@ configuring the Crossplane Pod settings in the
 Provide the name of the Provider's `.xpkg` file and set 
 {{<hover label="offline" line="7">}}packagePullPolicy: Never{{</hover>}}.
 
-For example, to install a locally downloaded version of Provider AWS set the 
+For example, to install a locally stored version of Provider AWS set the 
 {{<hover label="offline" line="6">}}package{{</hover>}} to the local filename
 and set the Provider's 
 {{<hover label="offline" line="7">}}packagePullPolicy: Never{{</hover>}}.
@@ -179,19 +179,21 @@ spec:
 # Removed for brevity
 ```
 
-#### Upgrade policy
+#### Revision activation policy
 
-Crossplane automatically upgrades a Provider the to the latest version available
-in the package cache. 
+The `Active` package revision
+is the package controller actively reconciling resources. 
+
+By default Crossplane sets the most recently installed package revision as 
+`Active`.
 
 Control the Provider upgrade behavior with a
 {{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}}.
 
 The {{<hover label="revision" line="6">}}revisionActivationPolicy{{</hover>}} 
 options are:
-* `Automatic` - (**default**) Automatically use the latest Provider version
-  available in the cache. 
-* `Manual` - Require the current Provider in use to be manually set. 
+* `Automatic` - (**default**) Automatically activate the last installed Provider.
+* `Manual` - Don't automatically activate a Provider.
 
 For example, to change the upgrade behavior to require manual upgrades, set 
 {{<hover label="revision" line="6">}}revisionActivationPolicy: Manual{{</hover>}}.
@@ -206,15 +208,6 @@ spec:
 # Removed for brevity
 ```
 
-{{<hint "important" >}}
-Crossplane only upgrades a Provider if a newer version is in the package cache.   
-By default the Crossplane [`packagePullPolicy`](#provider-pull-policy) doesn't
-download new Provider versions, even if they're available.
-{{< /hint >}}
-
-Read the [Provider upgrade](#upgrade-a-provider) section for
-more information on the use of package revisions.
-
 #### Package revision history limit
 
 When Crossplane installs a different version of the same Provider package 

utils/vale/styles/Crossplane/allowed-jargon.txt

@@ -28,6 +28,7 @@ float64
 imagePullSecret
 Go
 gRPC
+imagePullSecret
 JSONPath
 key-pair
 key-value
@@ -44,6 +45,8 @@ PersistentVolumeClaim
 PriorityClass
 proselint
 RBAC
+RPC
+RPCs
 SCSS
 SDK
 SDKs

utils/vale/styles/Google/Headings.yml

@@ -25,7 +25,6 @@ exceptions:
   - Composition
   - Compositions
   - Configuration
-  - configuration
   - Cosmos
   - Crossplane
   - Docker

utils/vale/styles/write-good/Weasel.yml

@@ -140,7 +140,6 @@ tokens:
   - rapidly
   - rarely
   - really
-  - recently
   - recklessly
   - regularly
   - remarkably