From 9ff5f3064905f1f016a169ac72defed92a65cfa0 Mon Sep 17 00:00:00 2001 From: Alexander Sher Date: Thu, 21 Nov 2019 11:44:41 -0800 Subject: [PATCH] Fix several documentation bugs (#8861) * - Fix #7227: Add CONTRIBUTING.md - Fix #8473: Add service level README - Fix #8651: Update docstrings * Update README.md * Address PR comments * Add service-level readme to the list of known issues * Use relative paths --- eng/.docsettings.yml | 1 + .../Azure.Data.AppConfiguration/README.md | 17 ++-- .../samples/README.md | 4 +- .../src/ConfigurationClient.cs | 18 +++-- .../ConfigurationClientBuilderExtensions.cs | 4 +- .../src/ConfigurationClientOptions.cs | 2 +- .../src/ConfigurationClient_private.cs | 2 +- .../src/ConfigurationModelFactory.cs | 2 +- .../src/ConfigurationSetting.cs | 2 +- .../src/SettingSelector.cs | 4 +- sdk/appconfiguration/CONTRIBUTING.md | 79 +++++++++++++++++++ sdk/appconfiguration/README.md | 21 +++++ .../src/Shared/ArrayBufferWriter.cs | 2 +- 13 files changed, 136 insertions(+), 22 deletions(-) create mode 100644 sdk/appconfiguration/CONTRIBUTING.md create mode 100644 sdk/appconfiguration/README.md diff --git a/eng/.docsettings.yml b/eng/.docsettings.yml index ad59dda24197..08afc581e1a7 100644 --- a/eng/.docsettings.yml +++ b/eng/.docsettings.yml @@ -65,6 +65,7 @@ known_content_issues: - ['sdk/servicebus/Microsoft.Azure.ServiceBus/README.md','#5499'] - ['sdk/eventhub/Microsoft.Azure.EventHubs/README.md','#5499'] - ['sdk/alertsmanagement/Microsoft.Azure.Management.AlertsManagement/README.md','#5499'] + - ['sdk/appconfiguration/README.md','azure-sdk-tools/issues/42'] - ['sdk/appconfiguration/Azure.Data.AppConfiguration/tests/Readme.md','#5499'] - ['sdk/appconfiguration/Azure.Data.AppConfiguration/samples/README.md','#5499'] - ['sdk/core/Azure.Core/README.md','#5499'] diff --git a/sdk/appconfiguration/Azure.Data.AppConfiguration/README.md b/sdk/appconfiguration/Azure.Data.AppConfiguration/README.md index 5305b7761cba..12c1b58e1cc0 100644 --- a/sdk/appconfiguration/Azure.Data.AppConfiguration/README.md +++ b/sdk/appconfiguration/Azure.Data.AppConfiguration/README.md @@ -212,20 +212,23 @@ Several App Configuration client library samples are available to you in this Gi ## Contributing -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.microsoft.com. +See the [App Configuration CONTRIBUTING.md][azconfig_contrib] for details on building, testing, and contributing to this library. + +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 [cla.microsoft.com][cla]. 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., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. -This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments. +This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information see the [Code of Conduct FAQ][code_of_conduct_faq] or contact [opencode@microsoft.com][email_opencode] with any additional questions or comments. ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Fappconfiguration%2FAzure.Data.AppConfiguration%2FREADME.png) [azconfig_docs]: https://docs.microsoft.com/azure/azure-app-configuration/ +[azconfig_contrib]: ../CONTRIBUTING.md [azconfig_setting_concepts]: https://docs.microsoft.com/en-us/azure/azure-app-configuration/concept-key-value [azconfig_asof_snapshot]: https://docs.microsoft.com/en-us/azure/azure-app-configuration/concept-point-time-snapshot -[source_root]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/appconfiguration/Azure.Data.AppConfiguration -[source_samples]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/appconfiguration/Azure.Data.AppConfiguration/samples +[source_root]: ./ +[source_samples]: ./samples [reference_docs]: https://azure.github.io/azure-sdk-for-net/appconfiguration.html [azconfig_rest]: https://github.com/Azure/AppConfiguration#rest-api-reference [azure_cli]: https://docs.microsoft.com/cli/azure @@ -235,5 +238,9 @@ This project has adopted the Microsoft Open Source Code of Conduct. For more inf [label_concept]: https://docs.microsoft.com/en-us/azure/azure-app-configuration/concept-key-value#label-keys [nuget]: https://www.nuget.org/ [package]: https://www.nuget.org/packages/Azure.ApplicationModel.Configuration/ -[samples_readme]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/appconfiguration/Azure.Data.AppConfiguration/samples/README.md +[samples_readme]: ./samples/README.md [moq]: https://github.com/Moq/moq4/ +[cla]: https://cla.microsoft.com +[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/ +[code_of_conduct_faq]: https://opensource.microsoft.com/codeofconduct/faq/ +[email_opencode]: mailto:opencode@microsoft.com diff --git a/sdk/appconfiguration/Azure.Data.AppConfiguration/samples/README.md b/sdk/appconfiguration/Azure.Data.AppConfiguration/samples/README.md index bc81af65efb1..a4fb8031e218 100644 --- a/sdk/appconfiguration/Azure.Data.AppConfiguration/samples/README.md +++ b/sdk/appconfiguration/Azure.Data.AppConfiguration/samples/README.md @@ -66,8 +66,8 @@ In this sample, we give a simple example illustrating how the [Moq](moq) library [azure_sub]: https://azure.microsoft.com/free/ [configuration_store]: https://docs.microsoft.com/azure/azure-app-configuration/quickstart-dotnet-core-app#create-an-app-configuration-store -[root_readme]: https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/appconfiguration/Azure.Data.AppConfiguration/README.md +[root_readme]: ../README.md [conditional_request_mdn]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests [conditional_request_guideline]: https://azure.github.io/azure-sdk/general_design.html#conditional-requests [moq]: https://github.com/Moq/moq4/ -[mock_tests]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/appconfiguration/Azure.Data.AppConfiguration/tests/ConfigurationMockTests.cs +[mock_tests]: ../tests/ConfigurationMockTests.cs diff --git a/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClient.cs b/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClient.cs index 8b8e594f37a5..c0e1ea2e87fb 100644 --- a/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClient.cs +++ b/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClient.cs @@ -392,9 +392,12 @@ public virtual Response DeleteConfigurationSetting(string key, string label = de return DeleteConfigurationSetting(key, label, default, cancellationToken); } + /// + /// Delete a from the configuration store. + /// /// The to delete. /// If set to true and the configuration setting exists in the configuration store, delete the setting - /// if the passed-in is the same version as the one in the configuration store. The setting versions + /// if the passed-in is the same version as the one in the configuration store. The setting versions /// are the same if their ETag fields match. If the two settings are different versions, this method will throw an exception to indicate /// that the setting in the configuration store was modified since it was last obtained by the client. /// A controlling the request lifetime. @@ -414,9 +417,12 @@ public virtual async Task DeleteConfigurationSettingAsync(Configuratio return await DeleteConfigurationSettingAsync(setting.Key, setting.Label, requestOptions, cancellationToken).ConfigureAwait(false); } + /// + /// Delete a from the configuration store. + /// /// The to delete. /// If set to true and the configuration setting exists in the configuration store, delete the setting - /// if the passed-in is the same version as the one in the configuration store. The setting versions + /// if the passed-in is the same version as the one in the configuration store. The setting versions /// are the same if their ETag fields match. If the two settings are different versions, this method will throw an exception to indicate /// that the setting in the configuration store was modified since it was last obtained by the client. /// A controlling the request lifetime. @@ -652,7 +658,7 @@ private Response GetConfigurationSetting(string key, strin } /// - /// Retrieves one or more that satisfy the options set in the . + /// Retrieves one or more entities that match the options specified in the passed-in . /// /// Options used to select a set of entities from the configuration store. /// A controlling the request lifetime. @@ -664,7 +670,7 @@ public virtual AsyncPageable GetConfigurationSettingsAsync } /// - /// Retrieves one or more that satisfies the options of the + /// Retrieves one or more entities that match the options specified in the passed-in . /// /// Set of options for selecting from the configuration store. /// A controlling the request lifetime. @@ -699,7 +705,7 @@ public virtual Pageable GetRevisions(string key, string la } /// - /// Retrieves the different revisions of a specific that satisfies the options of the + /// Retrieves the different revisions of a specific that satisfy the options of the . /// /// Set of options for selecting from the configuration store. /// A controlling the request lifetime. @@ -710,7 +716,7 @@ public virtual AsyncPageable GetRevisionsAsync(SettingSele } /// - /// Retrieves the different revisions of a specific that satisfies the options of the + /// Retrieves the different revisions of a specific that satisfy the options of the . /// /// Set of options for selecting from the configuration store. /// A controlling the request lifetime. diff --git a/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClientBuilderExtensions.cs b/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClientBuilderExtensions.cs index 103798cff6ad..21c10d94ffa8 100644 --- a/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClientBuilderExtensions.cs +++ b/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClientBuilderExtensions.cs @@ -7,12 +7,12 @@ namespace Microsoft.Extensions.Azure { /// - /// Extension methods to add client to clients builder + /// Extension methods to add client to clients builder. /// public static class ConfigurationClientBuilderExtensions { /// - /// Registers a instance with the provided + /// Registers a instance with the provided . /// public static IAzureClientBuilder AddConfigurationClient(this TBuilder builder, string connectionString) where TBuilder : IAzureClientFactoryBuilder diff --git a/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClientOptions.cs b/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClientOptions.cs index 287781d8aca0..635d207cf720 100644 --- a/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClientOptions.cs +++ b/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClientOptions.cs @@ -8,7 +8,7 @@ namespace Azure.Data.AppConfiguration { /// - /// Options that allow to configure the management of the request sent to the service + /// Options that allow users to configure the requests sent to the App Configuration service. /// public class ConfigurationClientOptions : ClientOptions { diff --git a/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClient_private.cs b/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClient_private.cs index 87e951db4971..707909b907dc 100644 --- a/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClient_private.cs +++ b/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationClient_private.cs @@ -193,7 +193,7 @@ private void BuildUriForRevisions(RequestUriBuilder builder, SettingSelector sel public override bool Equals(object obj) => base.Equals(obj); /// - /// Get a hash code for the ConfigurationSetting + /// Get a hash code for the ConfigurationSetting. /// [EditorBrowsable(EditorBrowsableState.Never)] public override int GetHashCode() => base.GetHashCode(); diff --git a/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationModelFactory.cs b/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationModelFactory.cs index 66c71f800da5..51caaef62a9d 100644 --- a/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationModelFactory.cs +++ b/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationModelFactory.cs @@ -6,7 +6,7 @@ namespace Azure.Data.AppConfiguration { /// - /// Configuration Setting model factory that enables mocking for the App Configuration client library + /// Configuration Setting model factory that enables mocking for the App Configuration client library. /// public static class ConfigurationModelFactory { diff --git a/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationSetting.cs b/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationSetting.cs index 5b7bbfffc6b2..5b6611f7b4e6 100644 --- a/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationSetting.cs +++ b/sdk/appconfiguration/Azure.Data.AppConfiguration/src/ConfigurationSetting.cs @@ -92,7 +92,7 @@ public IDictionary Tags public override bool Equals(object obj) => base.Equals(obj); /// - /// Get a hash code for the ConfigurationSetting + /// Get a hash code for the ConfigurationSetting. /// [EditorBrowsable(EditorBrowsableState.Never)] public override int GetHashCode() => base.GetHashCode(); diff --git a/sdk/appconfiguration/Azure.Data.AppConfiguration/src/SettingSelector.cs b/sdk/appconfiguration/Azure.Data.AppConfiguration/src/SettingSelector.cs index 635fedecb94e..06f852b11423 100644 --- a/sdk/appconfiguration/Azure.Data.AppConfiguration/src/SettingSelector.cs +++ b/sdk/appconfiguration/Azure.Data.AppConfiguration/src/SettingSelector.cs @@ -58,7 +58,7 @@ public SettingSelector() : this(Any, Any) { } /// the passed-in keys and labels. /// /// A key or key filter indicating which entities to select. - /// A label or label filter indicating which entities to select + /// A label or label filter indicating which entities to select. public SettingSelector(string key, string label = default) { Keys = new List @@ -80,7 +80,7 @@ public SettingSelector(string key, string label = default) public override bool Equals(object obj) => base.Equals(obj); /// - /// Get a hash code for the SettingSelector + /// Get a hash code for the SettingSelector. /// [EditorBrowsable(EditorBrowsableState.Never)] public override int GetHashCode() => base.GetHashCode(); diff --git a/sdk/appconfiguration/CONTRIBUTING.md b/sdk/appconfiguration/CONTRIBUTING.md new file mode 100644 index 000000000000..d7e4a83315c4 --- /dev/null +++ b/sdk/appconfiguration/CONTRIBUTING.md @@ -0,0 +1,79 @@ +# Contributing + +Thank you for your interest in contributing to the Azure App Configuration client library. As an open source effort, we're excited to welcome feedback and contributions from the community. A great first step in sharing your thoughts and understanding where help is needed would be to take a look at the [open issues][open_issues]. + +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 [cla.microsoft.com][cla]. + +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., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. + +## Code of conduct + +This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information see the [Code of Conduct FAQ][code_of_conduct_faq] or contact [opencode@microsoft.com][email_opencode] with any additional questions or comments. + +## Getting started + +Before working on a contribution, it would be beneficial to familiarize yourself with the process and guidelines used for the Azure SDKs so that your submission is consistent with the project standards and is ready to be accepted with fewer changes requested. In particular, it is recommended to review: + + - [Azure SDK README][sdk_readme], to learn more about the overall project and processes used. + - [Azure SDK Design Guidelines][sdk_design_guidelines], to understand the general guidelines for the Azure SDK across all languages and platforms. + - [Azure SDK Contributing Guide][sdk_contributing], for information about how to onboard and contribute to the overall Azure SDK ecosystem. + +## Azure SDK Design Guidelines for .NET + +These libraries follow the [Azure SDK Design Guidelines for .NET][sdk_design_guidelines_dotnet] and share a number of core features such as HTTP retries, logging, transport protocols, authentication protocols, etc., so that once you learn how to use these features in one client library, you will know how to use them in other client libraries. You can learn about these shared features in the [Azure.Core README][sdk_dotnet_code_readme]. + +## Public API changes + +To update [`Azure.Data.AppConfiguration.netstandard2.0.cs`][azconfig_api] after making changes to the public API, execute [`./eng/Export-API.ps1`][azconfig_export_api]. + +## Testing + +### Frameworks + +We use [nUnit 3][nunit] as our testing framework. + +[Azure.Core's testing framework][core_tests] is copied into our projects' `/TestFramework` folders by the build _(Please be sure to run all of the unit tests in `../../core/Azure.Core/Azure.Core.All.sln` if you make any changes here)_. + +### Sync/Async testing + +We expose all of our APIs with both sync and async variants. To avoid writing each of our tests twice, we automatically rewrite our async API calls into their sync equivalents. Simply write your tests using only async APIs and call `InstrumentClient` on any of our client objects. The test framework will wrap the client with a proxy that forwards everything to the sync overloads. Please note that a number of our helpers will automatically instrument clients they provide you. Visual Studio's test runner will show `*TestClass(True)` for the async variants and `*TestClass(False)` for the sync variants. + +### Recorded tests + +Our testing framework supports recording service requests made during a unit test so they can be replayed later. You can set the `AZURE_TEST_MODE` environment variable to `Playback` to run previously recorded tests, `Record` to record or re-record tests, and `Live` to run tests against the live service. + +Properly supporting recorded tests does require a few extra considerations. All random values should be obtained via `this.Recording.Random` since we use the same seed on test playback to ensure our client code generates the same "random" values each time. You can't share any state between tests or rely on ordering because you don't know the order they'll be recorded or replayed. Any sensitive values are redacted via the [`ConfigurationRecordedTestSanitizer`][tests_sanitized]. + +### Running tests + +The easiest way to run the tests is via Visual Studio's unit test runner. + +You can also run tests via the command line using `dotnet test`, but that will run tests for all supported platforms simultaneously and intermingle their output. You can run the tests for just one platform with `dotnet test -f netcoreapp2.1` or `dotnet test -f net461`. + +The recorded tests are run automatically on every pull request. Live tests are run nightly. Contributors with write access can ask Azure DevOps to run the live tests against a pull request by commenting `/azp run net - appconfiguration - tests` in the PR. + +### Samples + +Our samples are structured as unit tests so we can easily verify they're up to date and working correctly. These tests aren't recorded and make minimal use of test infrastructure to keep them easy to read. + +## Development history + +For additional insight and context, the development, release, and issue history for the Azure Event Hubs client library is available in read-only form, in its previous location, the [Azure App Configuration .NET repository](). + + +[azconfig_root]: ../../sdk/appconfiguration +[azconfig_api]: ./Azure.Data.AppConfiguration/api/Azure.Data.AppConfiguration.netstandard2.0.cs +[azconfig_export_api]: ../../eng/Export-API.ps1 +[cla]: https://cla.microsoft.com +[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/ +[code_of_conduct_faq]: https://opensource.microsoft.com/codeofconduct/faq/ +[core_tests]: ../../sdk/core/Azure.Core/tests/TestFramework +[nunit]: https://github.com/nunit/docs/wiki +[open_issues]: https://github.com/Azure/azure-sdk-for-net/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3AClient+label%3AAzConfig +[sdk_readme]: https://github.com/Azure/azure-sdk +[sdk_contributing]: ./CONTRIBUTING.md +[sdk_design_guidelines]: https://azure.github.io/azure-sdk/general_introduction.html +[sdk_design_guidelines_dotnet]: https://azure.github.io/azure-sdk/dotnet_introduction.html +[sdk_dotnet_code_readme]: ../../sdk/core/Azure.Core/README.md +[tests_sanitized]: ./Azure.Data.AppConfiguration/tests/ConfigurationRecordedTestSanitizer.cs +[email_opencode]: mailto:opencode@microsoft.com diff --git a/sdk/appconfiguration/README.md b/sdk/appconfiguration/README.md new file mode 100644 index 000000000000..52b3e18a067a --- /dev/null +++ b/sdk/appconfiguration/README.md @@ -0,0 +1,21 @@ +# Azure App Configuration client library for .NET + +Azure App Configuration is a managed service that helps developers centralize their application and feature settings simply and securely. + +- [Azure.Data.AppConfiguration][app_config] allows you to create and manage application configuration settings and retrieve their revisions from a specific point in time. + +## Contributing + +See the [CONTRIBUTING.md][contrib] for details on building, testing, and contributing to these libraries. + +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 [cla.microsoft.com][cla]. + +This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments. + + +[app_config]: ./Azure.Data.AppConfiguration/README.md +[contrib]: ./CONTRIBUTING.md +[cla]: https://cla.microsoft.com +[coc]: https://opensource.microsoft.com/codeofconduct/ +[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ +[coc_contact]: mailto:opencode@microsoft.com diff --git a/sdk/core/Azure.Core/src/Shared/ArrayBufferWriter.cs b/sdk/core/Azure.Core/src/Shared/ArrayBufferWriter.cs index 158fc77b7123..9fea9d2c34b0 100644 --- a/sdk/core/Azure.Core/src/Shared/ArrayBufferWriter.cs +++ b/sdk/core/Azure.Core/src/Shared/ArrayBufferWriter.cs @@ -83,7 +83,7 @@ public void Clear() } /// - /// Notifies that amount of data was written to the output / + /// Notifies that amount of data was written to the output /. /// /// /// Thrown when is negative.