Update docs to reflect field removals

docs/multi_credential_assignment.md

@@ -83,62 +83,53 @@ ignored.
 Under this model, the only purpose for `ask_credential_on_launch` is to signal
 that API clients should prompt the user for (optional) changes at launch time.
 
-Backwards Compatability Concerns
+Backwards Compatibility Concerns
 --------------------------------
-A variety of API clients rely on now-deprecated mechanisms for Credential
+Requests to update `JobTemplate.credential` and `JobTemplate.vault_credential`
-retrieval and assignment, and those are still supported in a backwards
+will no longer work. Example request format:
-compatible way under this new API change.  Requests to update
-`JobTemplate.credential` and `JobTemplate.vault_credential` will still behave
-as they did before:
 
 `PATCH /api/v2/job_templates/N/ {'credential': X, 'vault_credential': Y}`
 
-If the job template (with pk=N) only has 1 vault credential,
+This request will have no effect because support for using these
-that will be replaced with the new `Y` vault credential.
+fields has been removed.
 
-If the job template has multiple vault credentials, and these do not include
+The relationship `extra_credentials` is deprecated but still supported for now.
-`Y`, then the new list will _only_ contain the single vault credential `Y`
+Clients should favor the `credentials` relationship instead.
-specified in the deprecated request.
-
-If the JobTemplate already has the `Y` vault credential associated with it,
-then no change will take effect (the other vault credentials will not be
-removed in this case). This is so that clients making deprecated requests
-do not interfere with clients using the new `credentials` relation.
 
 `GET` requests to `/api/v2/job_templates/N/` and `/api/v2/jobs/N/`
-have traditionally included a variety of metadata in the response via
+will include this via `related_fields`:
-`related_fields`:
 
 ```
 {
     "related": {
         ...
-        "credential": "/api/v2/credentials/1/",
+        "credentials": "/api/v2/job_templates/5/credentials/",
-        "vault_credential": "/api/v2/credentials/3/",
         "extra_credentials": "/api/v2/job_templates/5/extra_credentials/",
     }
 }
 ```
 
-...and `summary_fields`:
+...and `summary_fields`, which is not included in list views:
 
 ```
 {
     "summary_fields": {
-        "credential": {
+        "credentials": [
-            "description": "",
+            {
-            "credential_type_id": 1,
+                "description": "",
-            "id": 1,
+                "credential_type_id": 5,
-            "kind": "ssh",
+                "id": 2,
-            "name": "Demo Credential"
+                "kind": "aws",
-        },
+                "name": "some-aws"
-        "vault_credential": {
+            },
-            "description": "",
+            {
-            "credential_type_id": 3,
+                "description": "",
-            "id": 3,
+                "credential_type_id": 10,
-            "kind": "vault",
+                "id": 4,
-            "name": "some-vault"
+                "kind": "gce",
-        },
+                "name": "some-gce"
+            }
+        ],
         "extra_credentials": [
             {
                 "description": "",
@@ -159,16 +150,15 @@ have traditionally included a variety of metadata in the response via
 }
 ```
 
-These metadata will continue to exist and function in a backwards-compatible way.
+The only difference between `credentials` and `extra_credentials` is that the
+latter is filtered to only show "cloud" type credentials, whereas the former
+can be used to manage all types of related credentials.
 
-The `/api/v2/job_templates/N/extra_credentials` endpoint has been deprecated, but
+The `/api/v2/job_templates/N/launch/` endpoint no longer provides
-will also continue to exist and function in the same manner for multiple releases.
+backwards compatible support for specifying credentials at launch time
-
+via the `credential` or `vault_credential` fields.
-The `/api/v2/job_templates/N/launch/` endpoint also provides
+The launch endpoint can still accept a list under the `extra_credentials` key,
-deprecated,backwards compatible support for specifying credentials at launch time
+but this is deprecated in favor `credentials`.
-via the `credential`, `vault_credential`, and `extra_credentials` fields:
-
-`POST /api/v2/job_templates/N/launch/ {'credential': A, 'vault_credential': B, 'extra_credentials': [C, D]}`
 
 
 Specifying Multiple Vault Credentials

docs/prompting.md

@@ -21,7 +21,7 @@ The standard pattern applies to fields
  - `diff_mode`
  - `verbosity`
 
-##### Non-Standard Cases (Credentials Changing in Tower 3.3)
+##### Non-Standard Cases
 
  - `ask_variables_on_launch` allows unrestricted use of
    - `extra_vars`
@@ -30,9 +30,7 @@ The standard pattern applies to fields
  - Enabled survey allows restricted use of
    - `extra_vars`, only for variables in survey (with qualifiers)
  - `ask_credential_on_launch` allows use of
-   - `credential`
+   - `credentials`
-   - `vault_credential` / `extra_credentials` / `credentials`
-     (version-dependent, see notes below)
  - `ask_inventory_on_launch` allows use of
    - `inventory`
 
@@ -42,16 +40,12 @@ spec to exist and `survey_enabled` to be true). On the other hand,
 if `ask_variables_on_launch` is true, users can provide any variables in
 extra_vars.
 
-_(supported, but deprecated)_ Prompting enablement for several types of
+Prompting enablement for all types of credentials is controlled by `ask_credential_on_launch`.
-credentials is controlled by a single
+Clients can manually provide a list of credentials of any type, but only 1 of _each_ type, in
-field. On launch, multiple types of credentials can be provided in their respective fields
+`credentials` on a POST to the launch endpoint.
-inside of `credential`, `vault_credential`, and `extra_credentials`. Providing
+If the job is being spawned by a saved launch configuration (such as a schedule),
-credentials that require password input from the user on launch is
+credentials are managed by the many-to-many relationship `credentials` relative
-allowed, and the password must be provided along-side the credential, of course.
+to the launch configuration object.
-
-If the job is being spawned using a saved launch configuration,
-all credential types are managed by a many-to-many relationship
-called `credentials` relative to the launch configuration object.
 The credentials in this relationship will either add to the job template's
 credential list, or replace a credential in the job template's list if it
 is the same type.
@@ -69,9 +63,9 @@ actions in the API.
    - can accept certain fields, with no user configuration
 
 When launching manually, certain restrictions apply to the use of credentials
- - if providing any of `credential`, `vault_credential`, and `extra_credentials`
+ - if providing deprecated `extra_credentials` this becomes the "legacy" method,
-   this becomes the "legacy" method, and imposes additional restrictions on
+   and imposes additional restrictions on relaunch,
-   relaunch, and is mutually exclusive with the use of `credentials` field
+   and is mutually exclusive with the use of `credentials` field
  - if providing `credentials`, existing credentials on the job template may
    only be removed if replaced by another credential of the same type
    this is so that relaunch will use the up-to-date credential on the template