Make package names consistent with official Azure SDKs

[heaths]

When not idiomatic, our guidelines state we should be consistent. That includes package names. While our statically-typed languages tend to favor a name in the package name e.g. (.NET) Azure.Security.KeyVault.{Keys, Secrets, Certificates, Administration}, our JavaScript and Python packages do not. So far, we seem to have more in common with Python packages, hence I recommend a pattern like so:

• azure_key_vault -> azure_keyvault (or azure_security_keyvault)
• azure_service_bus -> azure_sevicebus (or azure_messaging_servicebus)
• azure_event_grid -> azure_eventgrid (or azure_messaging_eventgrid)

If we were to use topic names, that would be the values in parens. Personally I like the brevity of Python (and JS, which uses @azure/keyvault for example), but wanted to open the discussion.

/cc @JeffreyRichter

[ctaggart]

Previous rename of the crates was in October #34.

[JeffreyRichter]

In C++ (which is the language most similar to Rust), we use namespaces such as Azure.Security.KeyVault.Keys; see https://github.com/Azure/azure-sdk-for-cpp/blob/master/sdk/keyvault/azure-security-keyvault-keys/inc/azure/keyvault/keys/key_client.hpp#L27

Since Rust doesn't have namespaces; I think package names should match our C++ guidelines (except for changing periods to kebaba/snake and all lowercase). I did find this RFC: https://github.com/rust-lang/rfcs/blob/master/text/0430-finalizing-naming-conventions.md

This indicates that crates should be snake_case.

[heaths]

If we hope to be an official SDK at some point, we need to be consistent when there's no idiomatic reason to not be. Maybe the track 2 SDKs should've used "Key Vault" as two words (in marketing it is, and I've made sure all our documentation reflects that at least in the KV SDK for .NET) but it's not that way in the official SDKs.

It also helps if the service directories match, e.g. sdk/keyvault. A lot of our common EngSys pipeline I'll get hooked up eventually works best when the service directories match across repos. Package names and all source beyond them e.g. sdk/keyvault/<package_name> can differ without issue.

[ctaggart]

My preference would be to roughly snake_case the product marketing and product documentation URLs, which are optionally grouped kebab-cased product names.

Product Marketing

• https://azure.microsoft.com/en-us/services/cosmos-db/
• https://azure.microsoft.com/en-us/services/event-grid/
• https://azure.microsoft.com/en-us/services/iot-hub/
• https://azure.microsoft.com/en-us/services/key-vault/
• https://azure.microsoft.com/en-us/services/service-bus/
• https://azure.microsoft.com/en-us/product-categories/storage/
  • https://azure.microsoft.com/en-us/services/storage/blobs/
  • https://azure.microsoft.com/en-us/services/storage/files/
  • https://azure.microsoft.com/en-us/services/storage/tables/
  • https://azure.microsoft.com/en-us/services/storage/queues/

Product Documentation

• https://docs.microsoft.com/en-us/azure/cosmos-db/
• https://docs.microsoft.com/en-us/azure/event-grid/
• https://docs.microsoft.com/en-us/azure/iot-hub/
• https://docs.microsoft.com/en-us/azure/key-vault/
• https://docs.microsoft.com/en-us/azure/service-bus-messaging/
• https://docs.microsoft.com/en-us/azure/storage/
  • https://docs.microsoft.com/en-us/azure/storage/blobs/
  • https://docs.microsoft.com/en-us/azure/storage/files/
  • https://docs.microsoft.com/en-us/azure/storage/tables/
  • https://docs.microsoft.com/en-us/azure/storage/queues/

Rust crates:

• azure_cosmos_db
• azure_event_grid
• azure_iot_hub
• azure_key_vault
• azure_service_bus
• azure_storage

Storage crates if we decide to separate them:

• azure_storage_blobs
• azure_storage_files
• azure_storage_tables
• azure_storage_queues

[ctaggart]

Using "Azure Key Vault" as an example, the new .NET packages are:
https://www.nuget.org/packages?q=KeyVault

• Azure.Security.KeyVault.Secrets
• Azure.Security.KeyVault.Keys

The .NET packages use PascalCase for "Key Vault", so it becomes "KeyVault". The kebab-case of "Key Vault" is what you see in the product marketing and product documentation URLs:

• https://azure.microsoft.com/en-us/services/key-vault/
• https://docs.microsoft.com/en-us/azure/key-vault/

For Rust, we should be using snake_case. The snake_case of "Key Vault" is "key_vault".

This is more consistent with SDKs like .NET than a convention to lowercase and remove the spaces that results in "keyvault".

[JeffreyRichter]

The Azure SDK team doesn't follow Azure branding for package/namespace naming. The reason why we don't is because branding changes. For example, Azure Storage Tables is now called Azure Cosmos Tables. So, the SDK team uses a pattern of Azure..Service. See https://azure.github.io/azure-sdk/general_design.html#namespaces

[heaths]

JS and Python use kebob case for package names and are still one word:

• https://www.npmjs.com/package/@azure/keyvault-secrets
• https://pypi.org/project/azure-keyvault-secrets/

The goal was to be consistent with the rest of the Azure SDKs in hopes that one day these may be official as well.

[ctaggart]

kebob case for Key Vault is key-vault. I'm not sure what naming convention to call keyvault.

[heaths]

"azure-keyvault" is kebob-cased. As @JeffreyRichter pointed out we don't treat Key Vault as two words in our packages - not in track 1 nor track 2 packages. The goal of the original repo was to be consistent where idiomacy didn't matter. Package names should be no different. Whether the original package names are wrong is irrelevant: they already GA'd that way years ago.

[ctaggart]

.NET packages use KeyVault, not Keyvault. It uses PascalCase on two words.

[heaths]

No separating dots, though. Track 1 was the same way. Same with Java. "Key Vault" is often colloquially referred to as "KeyVault". In fact, I fixed a lot of instance is documentation across properties some time back to refer to it as "Key Vault". Still doesn't change that packages with the structure documented here already shipped as they did, and having consistent APIs including package names is a goal of the Azure SDKs.

@JeffreyRichter I still don't see what benefit "Security" has in this example (or any topic-level name). If Go is allowed to use names as short as azkeyvault and Python and JS ship some variant of azure-keyvault, why not for Rust? A rough analysis of the crates.io index shows short names are preferred as well. The top 10 results account for almost 70% of the total length of names:

length(name)	count of name	percentage of total
7	5109	7.83%
8	5018	7.69%
10	4918	7.54%
9	4849	7.43%
6	4653	7.13%
3	4542	6.96%
11	4491	6.88%
12	3921	6.01%
5	3861	5.92%
4	3475	5.33%

(based on latest version of all crates using crates-index crate)

[ctaggart]

We discussed in Teams today and the result was this:

#[test]
fn test() {
    assert!( name_crate(["Azure", "Security", "Key Vault"]) == "azure_security_keyvault");
}

/// crates will be named <azure>_<group>_<service>
/// The group and service will be lowercase with spaces removed.
/// https://azure.github.io/azure-sdk/general_design.html#namespaces
pub fn name_crate(parts: [&str; 3]) -> String {
    let parts: Vec<_> = parts.iter().map(name_crate_part).collect();
    parts.join("_")
}

fn name_crate_part(part: &&str) -> String {
    part.to_lowercase().replace(" ", "")
}

https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=c9698afbe432393020025e2cef8d25ee

[ctaggart]

This is fixed by renaming these crates:

• azure_security_keyvault #441
• azure_messaging_eventgrid #442
• azure_messaging_servicebus #443
• azure_iot_hub #444

[ctaggart]

The other packages use approved namespaces :

• azure_core
• azure_identity
• azure_cosmos
• azure_storage

And correspond to those .NET packages:

• https://www.nuget.org/packages/Azure.Core/
• https://www.nuget.org/packages/Azure.Identity/
• https://www.nuget.org/packages/Azure.Cosmos/
• https://www.nuget.org/packages?q=Azure.Storage
  azure_storage uses features instead of separate packages:
  https://www.nuget.org/packages/Azure.Storage.Blobs/
  https://www.nuget.org/packages/Azure.Storage.Queues/
  https://www.nuget.org/packages/Azure.Storage.Files.Shares/

[cataggar]

This is complete.