Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the root readme #1732

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+37 −28
Open

Update the root readme #1732

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 37 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,32 @@
# Azure SDK for Rust

This repository is for the development of the [unofficial](https://github.com/Azure/azure-sdk-for-rust/blob/main/FAQ.md#why-is-it-unofficial) Azure SDK for Rust.
This repository is for the active development of the Azure SDK for Rust. For consumers of the SDK you can follow the links below to visit the documentation you are interested in
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Punctuation:

Suggested change
This repository is for the active development of the Azure SDK for Rust. For consumers of the SDK you can follow the links below to visit the documentation you are interested in
This repository is for the active development of the Azure SDK for Rust. For consumers of the SDK you can follow the links below to visit the documentation you are interested in.


## Crates
* [Overview of Azure SDK for Rust](https://docs.microsoft.com/azure/developer/rust/)
* [SDK Reference](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Go link?

* [Code Samples for Azure SDK for Rust](https://github.com/azure-samples/azure-sdk-for-rust-samples)
* [Azure REST API Docs](https://docs.microsoft.com/rest/api/)
* [General Azure Docs](https://docs.microsoft.com/azure)
* [Share your feedback to our Azure SDK](https://www.surveymonkey.com/r/FWPGFGG)

## Getting Started

To get started with a crate, see the README.md file located in the crate's project folder. You can find these crate folders grouped by service in the `/sdk` directory.

## Crates available

Each service can have both 'client' and 'management' crates. 'Client' crates are used to consume the service, whereas 'management' crates are used to configure and manage the service.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It may be first in a sentence, but the casing is specific. You can fix it with a colon.

Suggested change
Each service can have both 'client' and 'management' crates. 'Client' crates are used to consume the service, whereas 'management' crates are used to configure and manage the service.
Each service can have both 'client' and 'management' crates: 'client' crates are used to consume the service, whereas 'management' crates are used to configure and manage the service.


[All Azure SDK for Rust crates](https://crates.io/teams/github:azure:azure-sdk-publish-rust) are published on crates.io.

### SDK
These [SDK crates](sdk) are available:
- [azure_core](https://crates.io/crates/azure_core)
- [azure_identity](https://crates.io/crates/azure_identity)
- [azure_data_cosmos](https://crates.io/crates/azure_data_cosmos)
- [azure_data_tables](https://crates.io/crates/azure_data_tables)
- [azure_iot_hub](https://crates.io/crates/azure_iot_hub)
- [azure_security_keyvault](https://crates.io/crates/azure_security_keyvault)
- [azure_storage_blobs](https://crates.io/crates/azure_storage_blobs)
- [azure_storage_datalake](https://crates.io/crates/azure_storage_datalake)
- [azure_storage_queues](https://crates.io/crates/azure_storage_queues)
### Client modules

Our client crates follow the [Azure Rust SDK guidelines](https://azure.github.io/azure-sdk/rust_introduction.html). These crates allow you to use, consume, and interact with existing resources, for example, uploading a blob. They also share a number of core functionalities including retries, logging, transport protocols, authentication protocols, etc. that can be found in the [azure_identity](https://crates.io/crates/azure_identity) module.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consistency and punctuation:

Suggested change
Our client crates follow the [Azure Rust SDK guidelines](https://azure.github.io/azure-sdk/rust_introduction.html). These crates allow you to use, consume, and interact with existing resources, for example, uploading a blob. They also share a number of core functionalities including retries, logging, transport protocols, authentication protocols, etc. that can be found in the [azure_identity](https://crates.io/crates/azure_identity) module.
Our crates follow the [Azure SDK for Rust guidelines](https://azure.github.io/azure-sdk/rust_introduction.html). These crates allow you to use, consume, and interact with existing resources; for example, uploading a blob. They also share a number of core functionalities including retries, logging, transport protocols, authentication protocols, etc. that can be found in the [azure_identity](https://crates.io/crates/azure_identity) crate.


You can find the most up-to-date list of new modules on our [latest page](https://azure.github.io/azure-sdk/releases/latest/index.html#rust).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Translates better, if ever important:

Suggested change
You can find the most up-to-date list of new modules on our [latest page](https://azure.github.io/azure-sdk/releases/latest/index.html#rust).
You can find the most recent list of new crates on our [latest releases page](https://azure.github.io/azure-sdk/releases/latest/index.html#rust).

Also, stop calling them "modules". This isn't Go. 😄


> [!NOTE]
> If you need to ensure your code is ready for production use one of the stable, non-beta modules.

### Services
Azure service crates generated from [Azure REST API Specifications](https://github.com/Azure/azure-rest-api-specs) are available in [services](services).
Expand All @@ -25,28 +35,27 @@ Azure service crates generated from [Azure REST API Specifications](https://gith

🚨 WARNING 🚨: This project is under active development. Be aware that large breaking changes will happen before 1.0 is reached.

### Historical releases

This project is the successor to the `azure_sdk*` crates from [MindFlavor/AzureSDKForRust](https://github.com/MindFlavor/AzureSDKForRust). The crates have been renamed, so those older crates should be considered fully deprecated. See [history](HISTORY.md) for more details.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you also want to include a link to the legacy branch holding the unofficial Azure SDK Releases?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We haven't migrated yet and I don't think we should until we're ready to migrate feature/track2 to main. People are still actively contributing to main. I think at that time this README should reflect that information, though, yes.


## Project Structure
## Reporting security issues and security bugs

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) <secure@microsoft.com>. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the [Security TechCenter](https://www.microsoft.com/msrc/faqs-report-an-issue).

Each supported Azure service is its own separate crate.
## Need help?

Building each crate should be as straight forward as `cargo build`, but check each crate's README for more specific information.
* File an issue via [Github Issues](https://github.com/Azure/azure-sdk-for-rust/issues)
* Check [previous questions](https://stackoverflow.com/questions/tagged/azure+rust) or ask new ones on StackOverflow using `azure` and `rust` tags.
Comment on lines +48 to +49
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the order shouild be reversed. It's an unordered list, sure, but there's an implied order there. Also, there is a space in "Stack Overflow". It's a product name and should be referenced properly. GitHub also has a capital "G" and "H".

Suggested change
* File an issue via [Github Issues](https://github.com/Azure/azure-sdk-for-rust/issues)
* Check [previous questions](https://stackoverflow.com/questions/tagged/azure+rust) or ask new ones on StackOverflow using `azure` and `rust` tags.
* Check [previous questions](https://stackoverflow.com/questions/tagged/azure+rust) or ask new ones on Stack Overflow using `azure` and `rust` tags.
* File an issue via [GitHub Issues](https://github.com/Azure/azure-sdk-for-rust/issues)


### Mock testing framework
## Community

This library comes with a testing framework that executes against prerecorded sessions to quickly validate code changes without incurring in Azure costs. You can read more about it in the [Mock testing framework's README](https://github.com/Azure/azure-sdk-for-rust/tree/feature/track2/doc/mock_transport.md).
## Contribute
Comment on lines +51 to +53
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Empty heading.

We should put information that was here in a CONTRIBUTING.md at some point.


## Contributing
See [CONTRIBUTING.md](https://github.com/Azure/azure-sdk-for-go/blob/main/CONTRIBUTING.md).

This project welcomes contributions and suggestions. Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
provided by the bot. You will only need to do this once across all repos using our CLA.
## Trademarks

This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general). Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.