From f0a996250b97ebb42706ce8a73939f4484f22f6d Mon Sep 17 00:00:00 2001
From: Daniel Rodriguez <Daniel.Rodriguez@microsoft.com>
Date: Thu, 17 Dec 2020 23:56:32 +0000
Subject: [PATCH 01/16] migration guide wip

---
 .../keyvault-keys/migration-guide-template.md | 51 +++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 sdk/keyvault/keyvault-keys/migration-guide-template.md

diff --git a/sdk/keyvault/keyvault-keys/migration-guide-template.md b/sdk/keyvault/keyvault-keys/migration-guide-template.md
new file mode 100644
index 000000000000..135bf7ee347a
--- /dev/null
+++ b/sdk/keyvault/keyvault-keys/migration-guide-template.md
@@ -0,0 +1,51 @@
+# Guide for migrating to @azure/keyvault-keys from azure-keyvault
+
+This guide is intended to assist in the migration to `@azure/keyvault-keys` from `azure-keyvault`. It will focus on side-by-side comparisons for similar operations between the two packages.
+
+Familiarity with the `azure-keyvault` package is assumed. For those new to the Key Vault client libraries for JavaScript, please refer to the [README for name of new package here][kvk-readme] rather than this guide.
+
+## Table of contents
+
+## Migration benefits
+
+A natural question to ask when considering whether or not to adopt a new version or library is what the benefits of doing so would be. As Azure has matured and been embraced by a more diverse group of developers, we have been focused on learning the patterns and practices to best support developer productivity and to understand the gaps that the JavaScript client libraries have.
+
+There were several areas of consistent feedback expressed across the Azure client library ecosystem. One of the most important is that the client libraries for different Azure services have not had a consistent approach to organization, naming, and API structure. Additionally, many developers have felt that the learning curve was difficult, and the APIs did not offer a good, approachable, and consistent onboarding story for those learning Azure or exploring a specific Azure service.
+
+To try and improve the development experience across Azure services, a set of uniform [design guidelines](https://azure.github.io/azure-sdk/general_introduction.html) was created for all languages to drive a consistent experience with established API patterns for all services. A set of [add language here-specific guidelines][ts-guidelines] was also introduced to ensure that JavaScript clients have a natural and idiomatic feel with respect to the JavaScript and TypeScript ecosystems. Further details are available in the guidelines for those interested.
+
+### Cross Service SDK improvements
+
+The modern Key Vault client libraries also provide the ability to share in some of the cross-service improvements made to the Azure development experience, such as 
+- using the new Azure.Identity library to share a single authentication approach between clients
+- a unified logging and diagnostics pipeline offering a common view of the activities across each of the client libraries
+- (In case of JS) use of promises rather than callbacks for a simplified programming experience
+- (In case of JS) use of async iterators in paging APIs
+
+### Performance improvements
+
+Use this section to advertise the performance improvements in new package when compared to the old one. Skip this section if no perf improvements are found yet.
+
+## Important changes
+
+### Package names and namespaces
+
+Package names and the namespace root for the modern Azure client libraries for JavaScript have changed. Each will follow the pattern `@azure/[area and service]` where the legacy clients followed the pattern `azure-[area and service]`. This provides a quick and accessible means to help understand, at a glance, whether you are using the modern or legacy clients.
+
+In the case of Key Vault, the modern client libraries have packages and namespaces that begin with `@azure/keyvault-[specific functionality]` and were released beginning with version 5. The legacy client libraries have packages and namespaces that begin with Microsoft.Azure.EventHubs and a version of 4.x.x or below.
+
+### Client hierarchy and constructors
+
+If there has been no change (other than naming) in client hierarchy or entry level classes, skip "hierarchy" from the header, otherwise talk about why the client hierarchy was changed. Compare code snippets for the client constructors between the old and new packages, while pointing out differences and the reason behind them.
+
+### Champion scenario 1
+
+Repeat this section for the common high level usage scenarios for this library.
+Show how you would accomplish these both in the old and new packages, pointing out the key differences, reasons and advantages.
+
+## Additional samples
+
+More examples can be found at [Samples for add package name here](Add link to samples here)
+
+[kvk-readme]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-keys/README.md
+[ts-guidelines]: https://azure.github.io/azure-sdk/typescript_introduction.html

From abffd076c94ccaacd863cc14aa7cbc206dfcc8fe Mon Sep 17 00:00:00 2001
From: Daniel Rodriguez <Daniel.Rodriguez@microsoft.com>
Date: Fri, 18 Dec 2020 00:42:55 +0000
Subject: [PATCH 02/16] WIP

---
 .../keyvault-keys/migration-guide-template.md | 227 +++++++++++++++++-
 1 file changed, 218 insertions(+), 9 deletions(-)

diff --git a/sdk/keyvault/keyvault-keys/migration-guide-template.md b/sdk/keyvault/keyvault-keys/migration-guide-template.md
index 135bf7ee347a..d341b4507b21 100644
--- a/sdk/keyvault/keyvault-keys/migration-guide-template.md
+++ b/sdk/keyvault/keyvault-keys/migration-guide-template.md
@@ -6,6 +6,17 @@ Familiarity with the `azure-keyvault` package is assumed. For those new to the K
 
 ## Table of contents
 
+* [Migration benefits](#migration-benefits)
+* [Important changes](#important-changes)
+    - [Separate packages and clients](#separate-packages-and-clients)
+    - [Client constructors](#client-constructors)
+    - [Create a key](#create-a-key)
+    - [Retrieve a key](#retrieve-a-key)
+    - [List properties of keys](#list-properties-of-keys)
+    - [Delete a key](#delete-a-key)
+    - [Perform cryptographic operations](#perform-cryptographic-operations)
+* [Additional samples](#additional-samples)
+
 ## Migration benefits
 
 A natural question to ask when considering whether or not to adopt a new version or library is what the benefits of doing so would be. As Azure has matured and been embraced by a more diverse group of developers, we have been focused on learning the patterns and practices to best support developer productivity and to understand the gaps that the JavaScript client libraries have.
@@ -28,24 +39,222 @@ Use this section to advertise the performance improvements in new package when c
 
 ## Important changes
 
-### Package names and namespaces
+### Separate packages and clients
+
+In the interest of simplifying the API `azure-keyvault` and `KeyVaultClient` were split into separate packages and clients:
+
+- [`azure-keyvault-keys`][kvk-readme] contains `KeyClient` for working with keys and `CryptographyClient` for performing cryptographic operations.
+- [`azure-keyvault-secrets`][kvs-readme] contains `SecretClient` for working with secrets.
+- [`@azure/keyvault-certificates`][kvc-readme] contains `CertificateClient` for working with certificates.
+
+### Client constructors
+
+Across all modern Azure client libraries, clients consistently take an endpoint or connection string along with token credentials. This differs from `KeyVaultClient`, which took an authentication delegate and could be used for multiple Key Vault endpoints.
+
+#### Authenticating
+
+Previously in `azure-keyvault` you could create a `KeyVaultClient` by using credentials from `ms-rest-azure`:
+
+```js
+var KeyVault = require('azure-keyvault');
+var msRestAzure = require('ms-rest-azure');
+
+const clientId = "client id";
+const secret = "client secret";
+const domain = "tenant id";
+
+msRestAzure.loginWithServicePrincipalSecret(clientId, secret, domain, function(err, credentials) {
+  if (err) return console.log(err);
+  var client = new KeyVault.KeyVaultClient(credentials);
+});
+```
+
+Now in `@azure/keyvault-keys` you can create a `KeyClient` using any credential from [`@azure/identity`][identity-readme]. Below is an example using [`DefaultAzureCredential`][identity-readme-DAC]:
+
+```ts
+// The default credential first checks environment variables for configuration as described above.
+// If environment configuration is incomplete, it will try managed identity.
+const { KeyClient } = require("@azure/keyvault-keys");
+const { DefaultAzureCredential } = require("@azure/identity");
+
+// Azure SDK clients accept the credential as a parameter
+const credential = new DefaultAzureCredential();
+const vaultUrl = "https://my-key-vault.vault.azure.net/";
+const client = new KeyClient(vaultUrl, credential);
+const keyVaultKey = await client.getKey("MyKeyName");
+```
+
+You can also create a `CryptographyClient` to perform cryptographic operations (encrypt/decrypt, wrap/unwrap, sign/verify) using a particular key.
+
+```ts
+const { KeyClient, CryptographyClient } = require("@azure/keyvault-keys");
+const { DefaultAzureCredential } = require("@azure/identity");
+
+const credential = new DefaultAzureCredential();
+const vaultUrl = "https://my-key-vault.vault.azure.net/";
+const client = new KeyClient(vaultUrl, credential);
+const keyVaultKey = await client.getKey("MyKeyName");
+
+const cryptographyClient = new CryptographyClient(keyVaultKey.id!, credential);
+```
+
+### Create a key
+
+In `azure-keyvault` you could create a key by using `KeyVaultClient`'s `createKey` method, which required a vault endpoint, key name, and key type. This method returned a `KeyBundle` containing the key.
+
+```js
+// create an RSA key
+client.createKey(vaultUri, "mykey", "RSA").then((keyBundle) => {
+  console.log(keyBundle);
+});
+
+// create an elliptic curve key
+client.createKey(vaultUri, "mykey", "EC").then((keyBundle) => {
+  console.log(keyBundle);
+});
+```
+
+Now in `@azure/keyvault-keys` there are multiple ways to create keys. You can provide a key name and type to the general `createKey` method, or provide just a name to `createRsaKey` or `createEcKey`. These methods all return the created key as a `KeyVaultKey`.
+
+```ts
+const rsaKey1: KeyVaultKey = await keysClient.createKey("MyRSAKey1", "RSA");
+const rsaKey2: KeyVaultKey = await keysClient.createRsaKey("MyRSAKey2");
+const rsaEC1: KeyVaultKey = await keysClient.createKey("MyECKey1", "EC");
+const rsaEC2: KeyVaultKey = await keysClient.createEcKey("MyECKey2");
+```
+
+### Retrieve a key
+
+In `azure-keyvault` you could retrieve a key (in a `KeyBundle`) by using `getKey` and specifying the desired vault endpoint, key name, and key version. You could retrieve the versions of a key with the `getKeyVersions` method, which returned an iterator-like object.
+
+I AM HERE
+
+```python
+from azure.keyvault import KeyId
+
+key_items = client.get_key_versions(
+    vault_base_url="https://my-key-vault.vault.azure.net/",
+    key_name="key-name"
+)
+
+for key_item in key_items:
+    key_id = KeyId(key_item.kid)
+    key_version = key_id.version
+
+    key_bundle = client.get_key(
+        vault_base_url="https://my-key-vault.vault.azure.net/",
+        key_name="key-name",
+        key_version=key_version
+    )
+    key = key_bundle.key
+```
+
+Now in `azure-keyvault-keys` you can retrieve the latest version of a key (as a `KeyVaultKey`) by using `get_key` and providing a key name.
+
+```python
+key = key_client.get_key(name="key-name")
+
+print(key.name)
+print(key.key_type)
+
+# get the version of the key
+key_version = key.properties.version
+```
+
+### List properties of keys
+
+In `azure-keyvault` you could list the properties of keys in a specified vault with the `get_keys` method. This returned an iterator-like object containing `KeyItem` instances.
+
+```python
+keys = client.get_keys(vault_base_url="https://my-key-vault.vault.azure.net/")
+
+for key in keys:
+    print(key.attributes.created)
+```
+
+Now in `azure-keyvault-keys` you can list the properties of keys in a vault with the `list_properties_of_keys` method. This returns an iterator-like object containing `KeyProperties` instances.
+
+```python
+keys = key_client.list_properties_of_keys()
+
+for key in keys:
+    print(key.name)
+    print(key.created_on)
+```
+
+### Delete a key
+
+In `azure-keyvault` you could delete all versions of a key with the `delete_key` method. This returned information about the deleted key (as a `DeletedKeyBundle`), but you could not poll the deletion operation to know when it completed. This would be valuable information if you intended to permanently delete the deleted key with `purge_deleted_key`.
+
+```python
+deleted_key = client.delete_key(vault_base_url="https://my-key-vault.vault.azure.net/", key_name="key-name")
+
+# this purge would fail if deletion hadn't finished
+client.purge_deleted_key(vault_base_url="https://my-key-vault.vault.azure.net/", key_name="key-name")
+```
+
+Now in `azure-keyvault-keys` you can delete a key with `begin_delete_key`, which returns a long operation poller object that can be used to wait/check on the operation. Calling `result()` on the poller will return information about the deleted key (as a `DeletedKey`) without waiting for the operation to complete, but calling `wait()` will wait for the deletion to complete. Again, `purge_deleted_key` will permanently delete your deleted key and make it unrecoverable.
+
+```python
+deleted_key_poller = key_client.begin_delete_key(name="key-name")
+deleted_key = deleted_key_poller.result()
+
+deleted_key_poller.wait()
+key_client.purge_deleted_key(name="key-name")
+```
+
+### Perform cryptographic operations
+
+In `azure-keyvault` you could perform cryptographic operations with keys by using the `encrypt`/`decrypt`, `wrap_key`/`unwrap_key`, and `sign`/`verify` methods. Each of these methods accepted a vault endpoint, key name, key version, and algorithm along with other parameters.
+
+```python
+from azure.keyvault import KeyId
+
+key_bundle = client.create_key(
+    vault_base_url="https://my-key-vault.vault.azure.net/",
+    key_name="key-name",
+    kty="RSA"
+)
+key = key_bundle.key
+key_id = KeyId(key.kid)
+key_version = key_id.version
+
+plaintext = b"plaintext"
 
-Package names and the namespace root for the modern Azure client libraries for JavaScript have changed. Each will follow the pattern `@azure/[area and service]` where the legacy clients followed the pattern `azure-[area and service]`. This provides a quick and accessible means to help understand, at a glance, whether you are using the modern or legacy clients.
+# encrypt data using the key
+operation_result = client.encrypt(
+    vault_base_url="https://my-key-vault.vault.azure.net/",
+    key_name="key-name",
+    key_version=key_version,
+    algorithm="RSA-OAEP-256",
+    value=plaintext
+)
+ciphertext = operation_result.result
+```
 
-In the case of Key Vault, the modern client libraries have packages and namespaces that begin with `@azure/keyvault-[specific functionality]` and were released beginning with version 5. The legacy client libraries have packages and namespaces that begin with Microsoft.Azure.EventHubs and a version of 4.x.x or below.
+Now in `azure-keyvault-keys` you can perform these cryptographic operations by using a `CryptographyClient`. The key used to create the client will be used for these operations. Cryptographic operations are now performed locally by the client when it's intialized with the necessary key material or is able to get that material from Key Vault, and are only performed by the Key Vault service when required key material is unavailable.
 
-### Client hierarchy and constructors
+```python
+from azure.keyvault.keys.crypto import CryptographyClient, EncryptionAlgorithm
 
-If there has been no change (other than naming) in client hierarchy or entry level classes, skip "hierarchy" from the header, otherwise talk about why the client hierarchy was changed. Compare code snippets for the client constructors between the old and new packages, while pointing out differences and the reason behind them.
+key = key_client.get_key(name="key-name")
+crypto_client = CryptographyClient(key=key, credential=credential)
 
-### Champion scenario 1
+plaintext = b"plaintext"
 
-Repeat this section for the common high level usage scenarios for this library.
-Show how you would accomplish these both in the old and new packages, pointing out the key differences, reasons and advantages.
+# encrypt data using the key
+result = crypto_client.encrypt(algorithm=EncryptionAlgorithm.rsa_oaep_256, plaintext=plaintext)
+ciphertext = result.ciphertext
+```
 
 ## Additional samples
 
-More examples can be found at [Samples for add package name here](Add link to samples here)
+* [Key Vault keys samples for Python](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-keys/samples)
+* [General Key Vault samples for Python](https://docs.microsoft.com/samples/browse/?products=azure-key-vault&languages=python)
 
 [kvk-readme]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-keys/README.md
+[kvs-readme]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-secrets/README.md
+[kvc-readme]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-certificates/README.md
 [ts-guidelines]: https://azure.github.io/azure-sdk/typescript_introduction.html
+[identity-readme]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/identity/identity/README.md
+[identity-readme-DAC]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/identity/identity/README.md#defaultazurecredential

From 41e47a0e6ab3bfeb3a196eada495814c5fcf39cc Mon Sep 17 00:00:00 2001
From: Daniel Rodriguez <Daniel.Rodriguez@microsoft.com>
Date: Fri, 18 Dec 2020 13:50:16 +0000
Subject: [PATCH 03/16] wip

---
 .../keyvault-keys/migration-guide-template.md | 79 ++++++++++++-------
 1 file changed, 50 insertions(+), 29 deletions(-)

diff --git a/sdk/keyvault/keyvault-keys/migration-guide-template.md b/sdk/keyvault/keyvault-keys/migration-guide-template.md
index d341b4507b21..a51a70da92e0 100644
--- a/sdk/keyvault/keyvault-keys/migration-guide-template.md
+++ b/sdk/keyvault/keyvault-keys/migration-guide-template.md
@@ -53,7 +53,7 @@ Across all modern Azure client libraries, clients consistently take an endpoint
 
 #### Authenticating
 
-Previously in `azure-keyvault` you could create a `KeyVaultClient` by using credentials from `ms-rest-azure`:
+Previously in `azure-keyvault` you could create a `KeyVaultClient` by using credentials from `ms-rest-azure` (up to the version `2.6.0`. Higher versions are not supported):
 
 ```js
 var KeyVault = require('azure-keyvault');
@@ -62,11 +62,20 @@ var msRestAzure = require('ms-rest-azure');
 const clientId = "client id";
 const secret = "client secret";
 const domain = "tenant id";
-
-msRestAzure.loginWithServicePrincipalSecret(clientId, secret, domain, function(err, credentials) {
-  if (err) return console.log(err);
-  var client = new KeyVault.KeyVaultClient(credentials);
-});
+const vaultUrl = `https://my-vault.vault.azure.net/`;
+
+async function main() {
+  const credentials = await msRestAzure.loginWithServicePrincipalSecret(
+    clientId,
+    secret,
+    domain
+  );
+  const client = new KeyVault.KeyVaultClient(credentials);
+  const keyVaultKey = await client.getKey(vaultUrl, "MyKey", "");
+  console.log(keyVaultKey);
+}
+
+main().catch((err) => console.error(err));
 ```
 
 Now in `@azure/keyvault-keys` you can create a `KeyClient` using any credential from [`@azure/identity`][identity-readme]. Below is an example using [`DefaultAzureCredential`][identity-readme-DAC]:
@@ -79,9 +88,15 @@ const { DefaultAzureCredential } = require("@azure/identity");
 
 // Azure SDK clients accept the credential as a parameter
 const credential = new DefaultAzureCredential();
-const vaultUrl = "https://my-key-vault.vault.azure.net/";
+const vaultUrl = "https://my-vault.vault.azure.net/";
 const client = new KeyClient(vaultUrl, credential);
-const keyVaultKey = await client.getKey("MyKeyName");
+
+async function main(): Promise<void> {
+  const keyVaultKey = await client.getKey("MyKey");
+  console.log(keyVaultKey);
+}
+
+main().catch((err) => console.error(err));
 ```
 
 You can also create a `CryptographyClient` to perform cryptographic operations (encrypt/decrypt, wrap/unwrap, sign/verify) using a particular key.
@@ -91,11 +106,17 @@ const { KeyClient, CryptographyClient } = require("@azure/keyvault-keys");
 const { DefaultAzureCredential } = require("@azure/identity");
 
 const credential = new DefaultAzureCredential();
-const vaultUrl = "https://my-key-vault.vault.azure.net/";
+const vaultUrl = "https://my-vault.vault.azure.net/";
 const client = new KeyClient(vaultUrl, credential);
-const keyVaultKey = await client.getKey("MyKeyName");
 
-const cryptographyClient = new CryptographyClient(keyVaultKey.id!, credential);
+async function main(): Promise<void> {
+  const keyVaultKey = await client.getKey("MyKey");
+  const cryptographyClient = new CryptographyClient(keyVaultKey.id!, credential);
+  const signed = await cryptographyClient.signData("RS256", "some data");
+  console.log(signed);
+}
+
+main().catch((err) => console.error(err));
 ```
 
 ### Create a key
@@ -104,36 +125,36 @@ In `azure-keyvault` you could create a key by using `KeyVaultClient`'s `createKe
 
 ```js
 // create an RSA key
-client.createKey(vaultUri, "mykey", "RSA").then((keyBundle) => {
-  console.log(keyBundle);
-});
+let keyBundle = await client.createKey(vaultUrl, "myRSAKey", "RSA");
+console.log(keyBundle);
 
 // create an elliptic curve key
-client.createKey(vaultUri, "mykey", "EC").then((keyBundle) => {
-  console.log(keyBundle);
-});
+keyBundle = await client.createKey(vaultUrl, "myECKey", "EC")
+console.log(keyBundle);
 ```
 
 Now in `@azure/keyvault-keys` there are multiple ways to create keys. You can provide a key name and type to the general `createKey` method, or provide just a name to `createRsaKey` or `createEcKey`. These methods all return the created key as a `KeyVaultKey`.
 
 ```ts
-const rsaKey1: KeyVaultKey = await keysClient.createKey("MyRSAKey1", "RSA");
-const rsaKey2: KeyVaultKey = await keysClient.createRsaKey("MyRSAKey2");
-const rsaEC1: KeyVaultKey = await keysClient.createKey("MyECKey1", "EC");
-const rsaEC2: KeyVaultKey = await keysClient.createEcKey("MyECKey2");
+const rsaKey1 = await client.createKey("MyRSAKey1", "RSA");
+const rsaKey2 = await client.createRsaKey("MyRSAKey2");
+const ecKey1 = await client.createKey("MyECKey1", "EC");
+const ecKey2 = await client.createEcKey("MyECKey2");
 ```
 
 ### Retrieve a key
 
 In `azure-keyvault` you could retrieve a key (in a `KeyBundle`) by using `getKey` and specifying the desired vault endpoint, key name, and key version. You could retrieve the versions of a key with the `getKeyVersions` method, which returned an iterator-like object.
 
-I AM HERE
+```js
+YOU ARE HERE
+```
 
 ```python
 from azure.keyvault import KeyId
 
 key_items = client.get_key_versions(
-    vault_base_url="https://my-key-vault.vault.azure.net/",
+    vault_base_url="https://my-vault.vault.azure.net/",
     key_name="key-name"
 )
 
@@ -142,7 +163,7 @@ for key_item in key_items:
     key_version = key_id.version
 
     key_bundle = client.get_key(
-        vault_base_url="https://my-key-vault.vault.azure.net/",
+        vault_base_url="https://my-vault.vault.azure.net/",
         key_name="key-name",
         key_version=key_version
     )
@@ -166,7 +187,7 @@ key_version = key.properties.version
 In `azure-keyvault` you could list the properties of keys in a specified vault with the `get_keys` method. This returned an iterator-like object containing `KeyItem` instances.
 
 ```python
-keys = client.get_keys(vault_base_url="https://my-key-vault.vault.azure.net/")
+keys = client.get_keys(vault_base_url="https://my-vault.vault.azure.net/")
 
 for key in keys:
     print(key.attributes.created)
@@ -187,10 +208,10 @@ for key in keys:
 In `azure-keyvault` you could delete all versions of a key with the `delete_key` method. This returned information about the deleted key (as a `DeletedKeyBundle`), but you could not poll the deletion operation to know when it completed. This would be valuable information if you intended to permanently delete the deleted key with `purge_deleted_key`.
 
 ```python
-deleted_key = client.delete_key(vault_base_url="https://my-key-vault.vault.azure.net/", key_name="key-name")
+deleted_key = client.delete_key(vault_base_url="https://my-vault.vault.azure.net/", key_name="key-name")
 
 # this purge would fail if deletion hadn't finished
-client.purge_deleted_key(vault_base_url="https://my-key-vault.vault.azure.net/", key_name="key-name")
+client.purge_deleted_key(vault_base_url="https://my-vault.vault.azure.net/", key_name="key-name")
 ```
 
 Now in `azure-keyvault-keys` you can delete a key with `begin_delete_key`, which returns a long operation poller object that can be used to wait/check on the operation. Calling `result()` on the poller will return information about the deleted key (as a `DeletedKey`) without waiting for the operation to complete, but calling `wait()` will wait for the deletion to complete. Again, `purge_deleted_key` will permanently delete your deleted key and make it unrecoverable.
@@ -211,7 +232,7 @@ In `azure-keyvault` you could perform cryptographic operations with keys by usin
 from azure.keyvault import KeyId
 
 key_bundle = client.create_key(
-    vault_base_url="https://my-key-vault.vault.azure.net/",
+    vault_base_url="https://my-vault.vault.azure.net/",
     key_name="key-name",
     kty="RSA"
 )
@@ -223,7 +244,7 @@ plaintext = b"plaintext"
 
 # encrypt data using the key
 operation_result = client.encrypt(
-    vault_base_url="https://my-key-vault.vault.azure.net/",
+    vault_base_url="https://my-vault.vault.azure.net/",
     key_name="key-name",
     key_version=key_version,
     algorithm="RSA-OAEP-256",

From 51abb34dd2e5a004d199ded356f7bdacfcf784dd Mon Sep 17 00:00:00 2001
From: Daniel Rodriguez <Daniel.Rodriguez@microsoft.com>
Date: Fri, 18 Dec 2020 19:20:51 +0000
Subject: [PATCH 04/16] wip

---
 .../keyvault-keys/migration-guide-template.md | 69 ++++++++-----------
 1 file changed, 28 insertions(+), 41 deletions(-)

diff --git a/sdk/keyvault/keyvault-keys/migration-guide-template.md b/sdk/keyvault/keyvault-keys/migration-guide-template.md
index a51a70da92e0..c20bb0a8148f 100644
--- a/sdk/keyvault/keyvault-keys/migration-guide-template.md
+++ b/sdk/keyvault/keyvault-keys/migration-guide-template.md
@@ -144,63 +144,50 @@ const ecKey2 = await client.createEcKey("MyECKey2");
 
 ### Retrieve a key
 
-In `azure-keyvault` you could retrieve a key (in a `KeyBundle`) by using `getKey` and specifying the desired vault endpoint, key name, and key version. You could retrieve the versions of a key with the `getKeyVersions` method, which returned an iterator-like object.
+In `azure-keyvault` you could retrieve a key (in a `KeyBundle`) by using `getKey` and specifying the desired vault endpoint, key name, and key version. You could retrieve the versions of a key with the `getKeyVersions` method, which returned an array with key items that can be used to retrieve the full key afterwards.
 
 ```js
-YOU ARE HERE
-```
-
-```python
-from azure.keyvault import KeyId
+const keyItems = await client.getKeyVersions(vaultUrl, "MyKey");
 
-key_items = client.get_key_versions(
-    vault_base_url="https://my-vault.vault.azure.net/",
-    key_name="key-name"
-)
+for (let keyItem of keyItems) {
+  const version = keyItem.kid.split("/").pop();
+  console.log({ version });
 
-for key_item in key_items:
-    key_id = KeyId(key_item.kid)
-    key_version = key_id.version
-
-    key_bundle = client.get_key(
-        vault_base_url="https://my-vault.vault.azure.net/",
-        key_name="key-name",
-        key_version=key_version
-    )
-    key = key_bundle.key
+  const keyBundle = await client.getKey(vaultUrl, "MyKey", version);
+  console.log({ keyBundle });
+}
 ```
 
-Now in `azure-keyvault-keys` you can retrieve the latest version of a key (as a `KeyVaultKey`) by using `get_key` and providing a key name.
-
-```python
-key = key_client.get_key(name="key-name")
+Now in `@azure/keyvault-keys` you can retrieve the latest version of a key (as a `KeyVaultKey`) by using `getKey` and providing a key name. In addition, `listPropertiesOfKeyVersions` can be used to iterate over the versions of a specific key.
 
-print(key.name)
-print(key.key_type)
+```ts
+const keyVaultKey = await client.getKey("MyKey");
+console.log(keyVaultKey.name);
+console.log(keyVaultKey.keyType);
+console.log(keyVaultKey.properties.version);
 
-# get the version of the key
-key_version = key.properties.version
+for await (let versionProperties of client.listPropertiesOfKeyVersions("MyKey")) {
+  console.log("Version properties: ", versionProperties);
+}
 ```
 
 ### List properties of keys
 
-In `azure-keyvault` you could list the properties of keys in a specified vault with the `get_keys` method. This returned an iterator-like object containing `KeyItem` instances.
+In `azure-keyvault` you could list the properties of keys in a specified vault with the `getKeys` method. This returned an array containing the basic properties of each available key.
 
-```python
-keys = client.get_keys(vault_base_url="https://my-vault.vault.azure.net/")
-
-for key in keys:
-    print(key.attributes.created)
+```js
+const keyItems = await client.getKeys(vaultUrl);
+for (let keyItem of keyItems) {
+  console.log(keyItem.kid);
+}
 ```
 
-Now in `azure-keyvault-keys` you can list the properties of keys in a vault with the `list_properties_of_keys` method. This returns an iterator-like object containing `KeyProperties` instances.
-
-```python
-keys = key_client.list_properties_of_keys()
+Now in `@azure/keyvault-keys` you can list the properties of keys in a vault with the `listPropertiesOfKeys` method. This returns an iterator-like object containing `KeyProperties` instances.
 
-for key in keys:
-    print(key.name)
-    print(key.created_on)
+```ts
+for await (let keyProperties of client.listPropertiesOfKeys()) {
+    console.log("Key name: ", keyProperties.name);
+}
 ```
 
 ### Delete a key

From 548e17929ff0fd36af64051a0d686eeec07584e1 Mon Sep 17 00:00:00 2001
From: Daniel Rodriguez <Daniel.Rodriguez@microsoft.com>
Date: Fri, 18 Dec 2020 21:22:51 +0000
Subject: [PATCH 05/16] seems good for a draft

---
 .../keyvault-keys/migration-guide-template.md | 80 +++++++------------
 1 file changed, 28 insertions(+), 52 deletions(-)

diff --git a/sdk/keyvault/keyvault-keys/migration-guide-template.md b/sdk/keyvault/keyvault-keys/migration-guide-template.md
index c20bb0a8148f..695c5b121d32 100644
--- a/sdk/keyvault/keyvault-keys/migration-guide-template.md
+++ b/sdk/keyvault/keyvault-keys/migration-guide-template.md
@@ -167,7 +167,7 @@ console.log(keyVaultKey.keyType);
 console.log(keyVaultKey.properties.version);
 
 for await (let versionProperties of client.listPropertiesOfKeyVersions("MyKey")) {
-  console.log("Version properties: ", versionProperties);
+  console.log("Name:", versionProperties.name, "Version:", versionProperties.version);
 }
 ```
 
@@ -186,79 +186,55 @@ Now in `@azure/keyvault-keys` you can list the properties of keys in a vault wit
 
 ```ts
 for await (let keyProperties of client.listPropertiesOfKeys()) {
-    console.log("Key name: ", keyProperties.name);
+  console.log("Key name:", keyProperties.name);
 }
 ```
 
 ### Delete a key
 
-In `azure-keyvault` you could delete all versions of a key with the `delete_key` method. This returned information about the deleted key (as a `DeletedKeyBundle`), but you could not poll the deletion operation to know when it completed. This would be valuable information if you intended to permanently delete the deleted key with `purge_deleted_key`.
+In `azure-keyvault` you could delete all versions of a key with the `deleteKey` method. This returned information about the deleted key (as a `DeletedKeyBundle`), but you could not poll the deletion operation to know when it completed. This would be valuable information if you intended to permanently delete the deleted key with `purgeDeletedKey`.
 
-```python
-deleted_key = client.delete_key(vault_base_url="https://my-vault.vault.azure.net/", key_name="key-name")
-
-# this purge would fail if deletion hadn't finished
-client.purge_deleted_key(vault_base_url="https://my-vault.vault.azure.net/", key_name="key-name")
+```js
+const deletedKey = await client.deleteKey(vaultUrl, "MyKey");
+console.log(deletedKey.deletedDate);
+await client.purgeDeletedKey(vaultUrl, keyName);
 ```
 
-Now in `azure-keyvault-keys` you can delete a key with `begin_delete_key`, which returns a long operation poller object that can be used to wait/check on the operation. Calling `result()` on the poller will return information about the deleted key (as a `DeletedKey`) without waiting for the operation to complete, but calling `wait()` will wait for the deletion to complete. Again, `purge_deleted_key` will permanently delete your deleted key and make it unrecoverable.
-
-```python
-deleted_key_poller = key_client.begin_delete_key(name="key-name")
-deleted_key = deleted_key_poller.result()
+Now in `@azure/keyvault-keys` you can delete a key with `beginDeleteKey`, which returns a long operation poller object that can be used to wait/check on the operation. Calling `getResult()` on the poller will return information about the deleted key (as a `DeletedKey`) without waiting for the operation to complete, but calling `wait()` will wait for the deletion to complete. Again, `purge_deleted_key` will permanently delete your deleted key and make it unrecoverable.
 
-deleted_key_poller.wait()
-key_client.purge_deleted_key(name="key-name")
+```ts
+const deletePoller = await client.beginDeleteKey("MyKey");
+const deletedKey = deletePoller.getResult();
+await deletePoller.pollUntilDone();
+await client.purgeDeletedKey(deletedKey.name);
 ```
 
 ### Perform cryptographic operations
 
 In `azure-keyvault` you could perform cryptographic operations with keys by using the `encrypt`/`decrypt`, `wrap_key`/`unwrap_key`, and `sign`/`verify` methods. Each of these methods accepted a vault endpoint, key name, key version, and algorithm along with other parameters.
 
-```python
-from azure.keyvault import KeyId
-
-key_bundle = client.create_key(
-    vault_base_url="https://my-vault.vault.azure.net/",
-    key_name="key-name",
-    kty="RSA"
-)
-key = key_bundle.key
-key_id = KeyId(key.kid)
-key_version = key_id.version
-
-plaintext = b"plaintext"
-
-# encrypt data using the key
-operation_result = client.encrypt(
-    vault_base_url="https://my-vault.vault.azure.net/",
-    key_name="key-name",
-    key_version=key_version,
-    algorithm="RSA-OAEP-256",
-    value=plaintext
-)
-ciphertext = operation_result.result
+```js
+const keyName = "MyKey";
+await client.createKey(vaultUrl, keyName, "RSA");
+const operationResult = await client.encrypt(vaultUrl, keyName, "", "RSA1_5", Buffer.from("plaintext"));
+console.log(operationResult.result);
 ```
 
-Now in `azure-keyvault-keys` you can perform these cryptographic operations by using a `CryptographyClient`. The key used to create the client will be used for these operations. Cryptographic operations are now performed locally by the client when it's intialized with the necessary key material or is able to get that material from Key Vault, and are only performed by the Key Vault service when required key material is unavailable.
+Now in `@azure/keyvault-keys` you can perform these cryptographic operations by using a `CryptographyClient`. The key used to create the client will be used for these operations. Cryptographic operations are now performed locally by the client when it's initialized with the necessary key material or is able to get that material from Key Vault, and are only performed by the Key Vault service when required key material is unavailable.
 
-```python
-from azure.keyvault.keys.crypto import CryptographyClient, EncryptionAlgorithm
-
-key = key_client.get_key(name="key-name")
-crypto_client = CryptographyClient(key=key, credential=credential)
-
-plaintext = b"plaintext"
-
-# encrypt data using the key
-result = crypto_client.encrypt(algorithm=EncryptionAlgorithm.rsa_oaep_256, plaintext=plaintext)
-ciphertext = result.ciphertext
+```ts
+const keyVaultKey = await client.getKey("MyKey");
+const cryptographyClient = new CryptographyClient(keyVaultKey.id!, credential);
+const operationResult = await cryptographyClient.encrypt("RSA1_5", Buffer.from("plaintext"));
+console.log(operationResult.result);
 ```
 
 ## Additional samples
 
-* [Key Vault keys samples for Python](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/keyvault/azure-keyvault-keys/samples)
-* [General Key Vault samples for Python](https://docs.microsoft.com/samples/browse/?products=azure-key-vault&languages=python)
+* [Key Vault keys samples for JavaScript](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-keys/samples/javascript)
+* [General Key Vault samples for JavaScript](https://docs.microsoft.com/samples/browse/?products=azure-key-vault&languages=javascript)
+* [Key Vault keys samples for TypeScript](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/keyvault/keyvault-keys/samples/typescript)
+* [General Key Vault samples for TypeScript](https://docs.microsoft.com/samples/browse/?products=azure-key-vault&languages=typescript)
 
 [kvk-readme]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-keys/README.md
 [kvs-readme]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-secrets/README.md

From 698f9c015e31fd64462d612439ab2fb7a737c64b Mon Sep 17 00:00:00 2001
From: Daniel Rodriguez <Daniel.Rodriguez@microsoft.com>
Date: Fri, 18 Dec 2020 21:56:04 +0000
Subject: [PATCH 06/16] some improvements

---
 .../keyvault-keys/migration-guide-template.md | 50 +++++++++++++------
 1 file changed, 34 insertions(+), 16 deletions(-)

diff --git a/sdk/keyvault/keyvault-keys/migration-guide-template.md b/sdk/keyvault/keyvault-keys/migration-guide-template.md
index 695c5b121d32..83dd215dd8a3 100644
--- a/sdk/keyvault/keyvault-keys/migration-guide-template.md
+++ b/sdk/keyvault/keyvault-keys/migration-guide-template.md
@@ -23,19 +23,15 @@ A natural question to ask when considering whether or not to adopt a new version
 
 There were several areas of consistent feedback expressed across the Azure client library ecosystem. One of the most important is that the client libraries for different Azure services have not had a consistent approach to organization, naming, and API structure. Additionally, many developers have felt that the learning curve was difficult, and the APIs did not offer a good, approachable, and consistent onboarding story for those learning Azure or exploring a specific Azure service.
 
-To try and improve the development experience across Azure services, a set of uniform [design guidelines](https://azure.github.io/azure-sdk/general_introduction.html) was created for all languages to drive a consistent experience with established API patterns for all services. A set of [add language here-specific guidelines][ts-guidelines] was also introduced to ensure that JavaScript clients have a natural and idiomatic feel with respect to the JavaScript and TypeScript ecosystems. Further details are available in the guidelines for those interested.
+To try and improve the development experience across Azure services, a set of uniform [design guidelines](https://azure.github.io/azure-sdk/general_introduction.html) was created for all languages to drive a consistent experience with established API patterns for all services. A set of [TypeScript specific guidelines][ts-guidelines] was also introduced to ensure that JavaScript clients have a natural and idiomatic feel with respect to the JavaScript and TypeScript ecosystems. Further details are available in the guidelines for those interested.
 
 ### Cross Service SDK improvements
 
-The modern Key Vault client libraries also provide the ability to share in some of the cross-service improvements made to the Azure development experience, such as 
-- using the new Azure.Identity library to share a single authentication approach between clients
-- a unified logging and diagnostics pipeline offering a common view of the activities across each of the client libraries
-- (In case of JS) use of promises rather than callbacks for a simplified programming experience
-- (In case of JS) use of async iterators in paging APIs
-
-### Performance improvements
-
-Use this section to advertise the performance improvements in new package when compared to the old one. Skip this section if no perf improvements are found yet.
+The modern Key Vault client libraries also share some of the cross-service improvements made to the Azure development experience, such as:
+- Using the new `@azure/identity` library to share a single authentication approach between clients.
+- A unified logging and diagnostics pipeline that offers a common view of the activities across each of the client libraries.
+- (In case of JavaScript) The use of promises rather than callbacks for a simplified programming experience.
+- (In case of JavaScript) The use of async iterators in paging APIs.
 
 ## Important changes
 
@@ -43,17 +39,28 @@ Use this section to advertise the performance improvements in new package when c
 
 In the interest of simplifying the API `azure-keyvault` and `KeyVaultClient` were split into separate packages and clients:
 
-- [`azure-keyvault-keys`][kvk-readme] contains `KeyClient` for working with keys and `CryptographyClient` for performing cryptographic operations.
-- [`azure-keyvault-secrets`][kvs-readme] contains `SecretClient` for working with secrets.
+- [`@azure/keyvault-keys`][kvk-readme] contains `KeyClient` for working with Key Vault keys, and `CryptographyClient` for performing cryptographic operations.
+- [`@azure/keyvault-secrets`][kvs-readme] contains `SecretClient` for working with secrets.
 - [`@azure/keyvault-certificates`][kvc-readme] contains `CertificateClient` for working with certificates.
 
 ### Client constructors
 
-Across all modern Azure client libraries, clients consistently take an endpoint or connection string along with token credentials. This differs from `KeyVaultClient`, which took an authentication delegate and could be used for multiple Key Vault endpoints.
+Across all of the new Azure client libraries, clients consistently take an endpoint or connection string along with token credentials on their constructors. This differs from the legacy `KeyVaultClient`, which didn't receive the vault endpoint on the constructor, but required users to pass the vault endpoint as the first parameter to each one of the methods that the `KeyVaultClient` provided.
 
 #### Authenticating
 
-Previously in `azure-keyvault` you could create a `KeyVaultClient` by using credentials from `ms-rest-azure` (up to the version `2.6.0`. Higher versions are not supported):
+Previously in `azure-keyvault` you could create a `KeyVaultClient` by using credentials from `ms-rest-azure` (up to the version `2.6.0`. Higher versions are not supported).
+
+The dependencies on the `package.json` for a project with `azure-keyvault` would look like the following:
+
+```json
+  "dependencies": {
+    "azure-keyvault": "^3.0.5",
+    "ms-rest-azure": "^2.6.0"
+  }
+```
+
+With that `package.json` a simple use case of `azure-keyvault` would look as follows:
 
 ```js
 var KeyVault = require('azure-keyvault');
@@ -78,7 +85,18 @@ async function main() {
 main().catch((err) => console.error(err));
 ```
 
-Now in `@azure/keyvault-keys` you can create a `KeyClient` using any credential from [`@azure/identity`][identity-readme]. Below is an example using [`DefaultAzureCredential`][identity-readme-DAC]:
+Now in `@azure/keyvault-keys` you can create a `KeyClient` using any credential from [`@azure/identity`][identity-readme].
+
+The dependencies in your `package.json` would change to look as follows:
+
+```json
+  "dependencies": {
+    "@azure/identity": "1.2.1-alpha.20201217.1",
+    "@azure/keyvault-keys": "4.2.0-alpha.20201217.1",
+  }
+```
+
+Below is a simple example using both `@azure/keyvault-keys` and [`DefaultAzureCredential`][identity-readme-DAC]:
 
 ```ts
 // The default credential first checks environment variables for configuration as described above.
@@ -99,7 +117,7 @@ async function main(): Promise<void> {
 main().catch((err) => console.error(err));
 ```
 
-You can also create a `CryptographyClient` to perform cryptographic operations (encrypt/decrypt, wrap/unwrap, sign/verify) using a particular key.
+The new client also provides a `CryptographyClient` to perform cryptographic operations (encrypt/decrypt, wrap/unwrap, sign/verify) using a particular key. Below is an example.
 
 ```ts
 const { KeyClient, CryptographyClient } = require("@azure/keyvault-keys");

From f1d1268d3b4e3ac9582b044149f59b59e329cc77 Mon Sep 17 00:00:00 2001
From: Daniel Rodriguez <Daniel.Rodriguez@microsoft.com>
Date: Fri, 18 Dec 2020 22:40:10 +0000
Subject: [PATCH 07/16] last updates before submitting draft

---
 .../keyvault-keys/migration-guide-template.md   | 17 ++++++-----------
 1 file changed, 6 insertions(+), 11 deletions(-)

diff --git a/sdk/keyvault/keyvault-keys/migration-guide-template.md b/sdk/keyvault/keyvault-keys/migration-guide-template.md
index 83dd215dd8a3..baf77265eaa9 100644
--- a/sdk/keyvault/keyvault-keys/migration-guide-template.md
+++ b/sdk/keyvault/keyvault-keys/migration-guide-template.md
@@ -45,7 +45,7 @@ In the interest of simplifying the API `azure-keyvault` and `KeyVaultClient` wer
 
 ### Client constructors
 
-Across all of the new Azure client libraries, clients consistently take an endpoint or connection string along with token credentials on their constructors. This differs from the legacy `KeyVaultClient`, which didn't receive the vault endpoint on the constructor, but required users to pass the vault endpoint as the first parameter to each one of the methods that the `KeyVaultClient` provided.
+Across all of the new Azure client libraries, clients consistently take an endpoint or connection string along with token credentials on their constructors. This differs from the legacy `KeyVaultClient`, which didn't receive the vault endpoint on the constructor, but required users to pass the vault endpoint as the first parameter to the methods that the `KeyVaultClient` provided.
 
 #### Authenticating
 
@@ -87,14 +87,9 @@ main().catch((err) => console.error(err));
 
 Now in `@azure/keyvault-keys` you can create a `KeyClient` using any credential from [`@azure/identity`][identity-readme].
 
-The dependencies in your `package.json` would change to look as follows:
+You can install them by simply running the following command at the root of your project:
 
-```json
-  "dependencies": {
-    "@azure/identity": "1.2.1-alpha.20201217.1",
-    "@azure/keyvault-keys": "4.2.0-alpha.20201217.1",
-  }
-```
+  npm install --save @azure/identity @azure/keyvault-keys
 
 Below is a simple example using both `@azure/keyvault-keys` and [`DefaultAzureCredential`][identity-readme-DAC]:
 
@@ -218,7 +213,7 @@ console.log(deletedKey.deletedDate);
 await client.purgeDeletedKey(vaultUrl, keyName);
 ```
 
-Now in `@azure/keyvault-keys` you can delete a key with `beginDeleteKey`, which returns a long operation poller object that can be used to wait/check on the operation. Calling `getResult()` on the poller will return information about the deleted key (as a `DeletedKey`) without waiting for the operation to complete, but calling `wait()` will wait for the deletion to complete. Again, `purge_deleted_key` will permanently delete your deleted key and make it unrecoverable.
+Now in `@azure/keyvault-keys` you can delete a key with `beginDeleteKey`, which returns a long operation poller object that can be used to wait/check on the operation. Calling `getResult()` on the poller will return information about the deleted key (as a `DeletedKey`) without waiting for the operation to complete, but calling `pollUntilDone()` on the poller will wait for the deletion to complete. Then, `purgeDeletedKey` will permanently delete your deleted key and make it unrecoverable.
 
 ```ts
 const deletePoller = await client.beginDeleteKey("MyKey");
@@ -229,7 +224,7 @@ await client.purgeDeletedKey(deletedKey.name);
 
 ### Perform cryptographic operations
 
-In `azure-keyvault` you could perform cryptographic operations with keys by using the `encrypt`/`decrypt`, `wrap_key`/`unwrap_key`, and `sign`/`verify` methods. Each of these methods accepted a vault endpoint, key name, key version, and algorithm along with other parameters.
+In `azure-keyvault` you could perform cryptographic operations with keys by using the `encrypt`/`decrypt`, `wrapKey`/`unwrapKey`, and `sign`/`verify` methods. These methods accept a vault endpoint, key name, key version, and algorithm along with other parameters.
 
 ```js
 const keyName = "MyKey";
@@ -238,7 +233,7 @@ const operationResult = await client.encrypt(vaultUrl, keyName, "", "RSA1_5", Bu
 console.log(operationResult.result);
 ```
 
-Now in `@azure/keyvault-keys` you can perform these cryptographic operations by using a `CryptographyClient`. The key used to create the client will be used for these operations. Cryptographic operations are now performed locally by the client when it's initialized with the necessary key material or is able to get that material from Key Vault, and are only performed by the Key Vault service when required key material is unavailable.
+Now in `@azure/keyvault-keys` you can perform these cryptographic operations by using a `CryptographyClient`. The key used to create the client will be used for these operations. Some of the Cryptographic operations are now performed locally by the client when it's initialized with the necessary key material or is able to get that material from Key Vault.
 
 ```ts
 const keyVaultKey = await client.getKey("MyKey");

From 6358dd6b1ec136e739cbddbcf74918364226be81 Mon Sep 17 00:00:00 2001
From: Daniel Rodriguez <Daniel.Rodriguez@microsoft.com>
Date: Fri, 18 Dec 2020 22:47:45 +0000
Subject: [PATCH 08/16] ms-rest-azure version detail

---
 sdk/keyvault/keyvault-keys/migration-guide-template.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sdk/keyvault/keyvault-keys/migration-guide-template.md b/sdk/keyvault/keyvault-keys/migration-guide-template.md
index baf77265eaa9..ef0f00a7491d 100644
--- a/sdk/keyvault/keyvault-keys/migration-guide-template.md
+++ b/sdk/keyvault/keyvault-keys/migration-guide-template.md
@@ -49,7 +49,7 @@ Across all of the new Azure client libraries, clients consistently take an endpo
 
 #### Authenticating
 
-Previously in `azure-keyvault` you could create a `KeyVaultClient` by using credentials from `ms-rest-azure` (up to the version `2.6.0`. Higher versions are not supported).
+Previously in `azure-keyvault` you could create a `KeyVaultClient` by using credentials from `ms-rest-azure` (up to the version `^2.6.0`. Higher versions are not supported).
 
 The dependencies on the `package.json` for a project with `azure-keyvault` would look like the following:
 

From f33d0d07686d8977c15893a4aec009494076724d Mon Sep 17 00:00:00 2001
From: Daniel Rodriguez <Daniel.Rodriguez@microsoft.com>
Date: Fri, 18 Dec 2020 22:48:25 +0000
Subject: [PATCH 09/16] renamed to migration-guide.md

---
 .../{migration-guide-template.md => migration-guide.md}           | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename sdk/keyvault/keyvault-keys/{migration-guide-template.md => migration-guide.md} (100%)

diff --git a/sdk/keyvault/keyvault-keys/migration-guide-template.md b/sdk/keyvault/keyvault-keys/migration-guide.md
similarity index 100%
rename from sdk/keyvault/keyvault-keys/migration-guide-template.md
rename to sdk/keyvault/keyvault-keys/migration-guide.md

From b3a9f3217a256770725b6919ac774e454675d956 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Rodr=C3=ADguez?=
 <sadasant@users.noreply.github.com>
Date: Fri, 18 Dec 2020 18:39:02 -0500
Subject: [PATCH 10/16] keyName undefined in this line

---
 sdk/keyvault/keyvault-keys/migration-guide.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sdk/keyvault/keyvault-keys/migration-guide.md b/sdk/keyvault/keyvault-keys/migration-guide.md
index ef0f00a7491d..05b432214b01 100644
--- a/sdk/keyvault/keyvault-keys/migration-guide.md
+++ b/sdk/keyvault/keyvault-keys/migration-guide.md
@@ -210,7 +210,7 @@ In `azure-keyvault` you could delete all versions of a key with the `deleteKey`
 ```js
 const deletedKey = await client.deleteKey(vaultUrl, "MyKey");
 console.log(deletedKey.deletedDate);
-await client.purgeDeletedKey(vaultUrl, keyName);
+await client.purgeDeletedKey(vaultUrl, "MyKey");
 ```
 
 Now in `@azure/keyvault-keys` you can delete a key with `beginDeleteKey`, which returns a long operation poller object that can be used to wait/check on the operation. Calling `getResult()` on the poller will return information about the deleted key (as a `DeletedKey`) without waiting for the operation to complete, but calling `pollUntilDone()` on the poller will wait for the deletion to complete. Then, `purgeDeletedKey` will permanently delete your deleted key and make it unrecoverable.

From cf4e574da24c215266ebcbcd956ac69ec3340845 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Rodr=C3=ADguez?=
 <sadasant@users.noreply.github.com>
Date: Fri, 18 Dec 2020 18:54:54 -0500
Subject: [PATCH 11/16] npm command in better code block

---
 sdk/keyvault/keyvault-keys/migration-guide.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/sdk/keyvault/keyvault-keys/migration-guide.md b/sdk/keyvault/keyvault-keys/migration-guide.md
index 05b432214b01..de843bd94144 100644
--- a/sdk/keyvault/keyvault-keys/migration-guide.md
+++ b/sdk/keyvault/keyvault-keys/migration-guide.md
@@ -89,7 +89,9 @@ Now in `@azure/keyvault-keys` you can create a `KeyClient` using any credential
 
 You can install them by simply running the following command at the root of your project:
 
-  npm install --save @azure/identity @azure/keyvault-keys
+```
+npm install --save @azure/identity @azure/keyvault-keys
+```
 
 Below is a simple example using both `@azure/keyvault-keys` and [`DefaultAzureCredential`][identity-readme-DAC]:
 

From fe2969f93f1d56de109f0061af4365b3823ab45e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Rodr=C3=ADguez?=
 <sadasant@users.noreply.github.com>
Date: Fri, 18 Dec 2020 18:58:26 -0500
Subject: [PATCH 12/16] Improvement on the getKey example

---
 sdk/keyvault/keyvault-keys/migration-guide.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/sdk/keyvault/keyvault-keys/migration-guide.md b/sdk/keyvault/keyvault-keys/migration-guide.md
index de843bd94144..5a65cfc87d38 100644
--- a/sdk/keyvault/keyvault-keys/migration-guide.md
+++ b/sdk/keyvault/keyvault-keys/migration-guide.md
@@ -183,6 +183,8 @@ console.log(keyVaultKey.properties.version);
 
 for await (let versionProperties of client.listPropertiesOfKeyVersions("MyKey")) {
   console.log("Name:", versionProperties.name, "Version:", versionProperties.version);
+  const keyVaultKey = await client.getKey(versionProperties.name, { version: versionProperties.version });
+  console.log(keyVaultKey.properties.version);
 }
 ```
 

From 901eeb53a036c80a10fc29073097950554fcf0b2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Rodr=C3=ADguez?=
 <sadasant@users.noreply.github.com>
Date: Fri, 18 Dec 2020 19:06:58 -0500
Subject: [PATCH 13/16] Apply suggestions from code review

Co-authored-by: Ramya Rao <ramya.rao.a@outlook.com>
---
 sdk/keyvault/keyvault-keys/migration-guide.md | 22 +++++--------------
 1 file changed, 6 insertions(+), 16 deletions(-)

diff --git a/sdk/keyvault/keyvault-keys/migration-guide.md b/sdk/keyvault/keyvault-keys/migration-guide.md
index 5a65cfc87d38..25c64afe2324 100644
--- a/sdk/keyvault/keyvault-keys/migration-guide.md
+++ b/sdk/keyvault/keyvault-keys/migration-guide.md
@@ -2,7 +2,7 @@
 
 This guide is intended to assist in the migration to `@azure/keyvault-keys` from `azure-keyvault`. It will focus on side-by-side comparisons for similar operations between the two packages.
 
-Familiarity with the `azure-keyvault` package is assumed. For those new to the Key Vault client libraries for JavaScript, please refer to the [README for name of new package here][kvk-readme] rather than this guide.
+Familiarity with the `azure-keyvault` package is assumed. For those new to the Key Vault client libraries for JavaScript, please refer to the [README for name of @azure/keyvault-keys here][kvk-readme] rather than this guide.
 
 ## Table of contents
 
@@ -30,18 +30,18 @@ To try and improve the development experience across Azure services, a set of un
 The modern Key Vault client libraries also share some of the cross-service improvements made to the Azure development experience, such as:
 - Using the new `@azure/identity` library to share a single authentication approach between clients.
 - A unified logging and diagnostics pipeline that offers a common view of the activities across each of the client libraries.
-- (In case of JavaScript) The use of promises rather than callbacks for a simplified programming experience.
-- (In case of JavaScript) The use of async iterators in paging APIs.
+- The use of promises rather than callbacks for a simplified programming experience.
+- The use of async iterators in paging APIs.
 
 ## Important changes
 
 ### Separate packages and clients
 
-In the interest of simplifying the API `azure-keyvault` and `KeyVaultClient` were split into separate packages and clients:
+In the interest of simplifying the API for working with Key Vault keys, secrets and certificates, the `azure-keyvault`  package is split into separate packages.
 
 - [`@azure/keyvault-keys`][kvk-readme] contains `KeyClient` for working with Key Vault keys, and `CryptographyClient` for performing cryptographic operations.
-- [`@azure/keyvault-secrets`][kvs-readme] contains `SecretClient` for working with secrets.
-- [`@azure/keyvault-certificates`][kvc-readme] contains `CertificateClient` for working with certificates.
+- [`@azure/keyvault-secrets`][kvs-readme] contains `SecretClient` for working with Key Vault secrets.
+- [`@azure/keyvault-certificates`][kvc-readme] contains `CertificateClient` for working with Key Vault certificates.
 
 ### Client constructors
 
@@ -51,16 +51,6 @@ Across all of the new Azure client libraries, clients consistently take an endpo
 
 Previously in `azure-keyvault` you could create a `KeyVaultClient` by using credentials from `ms-rest-azure` (up to the version `^2.6.0`. Higher versions are not supported).
 
-The dependencies on the `package.json` for a project with `azure-keyvault` would look like the following:
-
-```json
-  "dependencies": {
-    "azure-keyvault": "^3.0.5",
-    "ms-rest-azure": "^2.6.0"
-  }
-```
-
-With that `package.json` a simple use case of `azure-keyvault` would look as follows:
 
 ```js
 var KeyVault = require('azure-keyvault');

From e217623a3370b6446e5a43e5836f5ece98dd7991 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Rodr=C3=ADguez?=
 <sadasant@users.noreply.github.com>
Date: Fri, 18 Dec 2020 20:00:31 -0500
Subject: [PATCH 14/16] Some of the feedback

---
 sdk/keyvault/keyvault-keys/migration-guide.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/sdk/keyvault/keyvault-keys/migration-guide.md b/sdk/keyvault/keyvault-keys/migration-guide.md
index 25c64afe2324..7d87393358e8 100644
--- a/sdk/keyvault/keyvault-keys/migration-guide.md
+++ b/sdk/keyvault/keyvault-keys/migration-guide.md
@@ -141,10 +141,17 @@ console.log(keyBundle);
 Now in `@azure/keyvault-keys` there are multiple ways to create keys. You can provide a key name and type to the general `createKey` method, or provide just a name to `createRsaKey` or `createEcKey`. These methods all return the created key as a `KeyVaultKey`.
 
 ```ts
+// create RSA keys
 const rsaKey1 = await client.createKey("MyRSAKey1", "RSA");
+console.log(rsaKey1);
 const rsaKey2 = await client.createRsaKey("MyRSAKey2");
+console.log(rsaKey2);
+
+// create elliptic curve keys
 const ecKey1 = await client.createKey("MyECKey1", "EC");
+console.log(ecKey1);
 const ecKey2 = await client.createEcKey("MyECKey2");
+console.log(ecKey2);
 ```
 
 ### Retrieve a key
@@ -193,7 +200,7 @@ Now in `@azure/keyvault-keys` you can list the properties of keys in a vault wit
 
 ```ts
 for await (let keyProperties of client.listPropertiesOfKeys()) {
-  console.log("Key name:", keyProperties.name);
+  console.log("Key Id:", keyProperties.id);
 }
 ```
 

From b4f1b18f5c0f83c4ca1807d1ddde1d0c905ce67e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Rodr=C3=ADguez?=
 <sadasant@users.noreply.github.com>
Date: Fri, 18 Dec 2020 20:02:16 -0500
Subject: [PATCH 15/16] Update sdk/keyvault/keyvault-keys/migration-guide.md

Co-authored-by: Ramya Rao <ramya.rao.a@outlook.com>
---
 sdk/keyvault/keyvault-keys/migration-guide.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sdk/keyvault/keyvault-keys/migration-guide.md b/sdk/keyvault/keyvault-keys/migration-guide.md
index 7d87393358e8..ef96537cef97 100644
--- a/sdk/keyvault/keyvault-keys/migration-guide.md
+++ b/sdk/keyvault/keyvault-keys/migration-guide.md
@@ -2,7 +2,7 @@
 
 This guide is intended to assist in the migration to `@azure/keyvault-keys` from `azure-keyvault`. It will focus on side-by-side comparisons for similar operations between the two packages.
 
-Familiarity with the `azure-keyvault` package is assumed. For those new to the Key Vault client libraries for JavaScript, please refer to the [README for name of @azure/keyvault-keys here][kvk-readme] rather than this guide.
+Familiarity with the `azure-keyvault` package is assumed. For those new to the Key Vault client libraries for JavaScript, please refer to the [README for @azure/keyvault-keys][kvk-readme] rather than this guide.
 
 ## Table of contents
 

From 4433e22d55a950912557dd22aa0838efea95f048 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Rodr=C3=ADguez?=
 <sadasant@users.noreply.github.com>
Date: Fri, 18 Dec 2020 20:06:22 -0500
Subject: [PATCH 16/16] More of the feedback

---
 sdk/keyvault/keyvault-keys/migration-guide.md | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/sdk/keyvault/keyvault-keys/migration-guide.md b/sdk/keyvault/keyvault-keys/migration-guide.md
index ef96537cef97..42a6f2a63c81 100644
--- a/sdk/keyvault/keyvault-keys/migration-guide.md
+++ b/sdk/keyvault/keyvault-keys/migration-guide.md
@@ -39,9 +39,9 @@ The modern Key Vault client libraries also share some of the cross-service impro
 
 In the interest of simplifying the API for working with Key Vault keys, secrets and certificates, the `azure-keyvault`  package is split into separate packages.
 
-- [`@azure/keyvault-keys`][kvk-readme] contains `KeyClient` for working with Key Vault keys, and `CryptographyClient` for performing cryptographic operations.
-- [`@azure/keyvault-secrets`][kvs-readme] contains `SecretClient` for working with Key Vault secrets.
-- [`@azure/keyvault-certificates`][kvc-readme] contains `CertificateClient` for working with Key Vault certificates.
+- [`@azure/keyvault-keys`][kvk-npm] contains `KeyClient` for working with Key Vault keys, and `CryptographyClient` for performing cryptographic operations.
+- [`@azure/keyvault-secrets`][kvs-npm] contains `SecretClient` for working with Key Vault secrets.
+- [`@azure/keyvault-certificates`][kvc-npm] contains `CertificateClient` for working with Key Vault certificates.
 
 ### Client constructors
 
@@ -253,6 +253,9 @@ console.log(operationResult.result);
 [kvk-readme]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-keys/README.md
 [kvs-readme]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-secrets/README.md
 [kvc-readme]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-certificates/README.md
+[kvk-npm]: https://www.npmjs.com/package/@azure/keyvault-keys
+[kvs-npm]: https://www.npmjs.com/package/@azure/keyvault-secrets
+[kvc-npm]: https://www.npmjs.com/package/@azure/keyvault-certificates
 [ts-guidelines]: https://azure.github.io/azure-sdk/typescript_introduction.html
 [identity-readme]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/identity/identity/README.md
 [identity-readme-DAC]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/identity/identity/README.md#defaultazurecredential