From 1151719d6fb15012616583077720ff0236a65b08 Mon Sep 17 00:00:00 2001 From: "Jiefeng Chen (WICRESOFT NORTH AMERICA LTD)" Date: Tue, 24 May 2022 16:40:53 +0800 Subject: [PATCH 01/11] create doc --- doc/resolve_issues_effectively.md | 59 +++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 doc/resolve_issues_effectively.md diff --git a/doc/resolve_issues_effectively.md b/doc/resolve_issues_effectively.md new file mode 100644 index 000000000000..4e15b57ae7fa --- /dev/null +++ b/doc/resolve_issues_effectively.md @@ -0,0 +1,59 @@ +# Resolve Issues Effectively + +Azure Python SDK is an open-source project. It allows users to create issues in the forum to ask questions, report bugs and provide feedback. + +Most issues can be classified into 3 categories. They are + +1. Usage error. +2. Feature request. +3. Bug report. + +## Usage error (For users) +If you are not familiar with the SDK usage of a service, you can find relevant examples in [this repo][sample repo] in most cases. + +## Feature Request(For users) + +See [here][request_a_feature] for more details. + +## Bug Report (For users) + +Please describe the bug in as much detail as possible, such as listing the SDK package name, version and operating system info you use. + +If you can provide detailed reproduction steps, it will help us locate and solve the issue. + +
+ +## Resolve issue (For contributors) + +Bug report is one of the most common issues reported in open-source community. Basic steps to resolve a bug report are + +1. Confirm the bug. +2. Locate the fault. +3. Fix the bug. + +### Confirm the Bug + +Confirm whether it is a bug. If you can definitely identify it is a bug according description of the issue, then go to next step. Otherwise, try to reproduce the bug by yourself. You can ask the issue reporter for details such as version, concrete steps and logs so that you can understand the issue better and it is more likely to be able to reproduce the bug. It is not rare that it is not a bug. Instead, it is a usage error. Refer to "Usage Error" section. + +### Locate the Fault + +Fault localization is critical to bug fix. Some tips: + +1. Analyzing logs. It helps you understand the bug. + +2. Step-by-step debugging. Most modern IDEs provide integrated debugging experience. + + +### Fix the bug + +Once you have confirmed the bug and found the fault location, it should be easy to fix the bug. Add a sample if it is missing. Remember to tell users when the fix will released. + + +## Common Principles + +If the issue is not from the SDK but from the [rest API][rest API], you can reply to the user and reopen the issue in the appropriate place. + + +[sample repo]: https://github.com/Azure-Samples/azure-samples-python-management +[request_a_feature]: https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/how_to_request_a_feature_in_sdk.md +[rest API]: https://github.com/Azure/azure-rest-api-specs \ No newline at end of file From 3232a62e2648c9ffe9ec45ac6484b53470b81c24 Mon Sep 17 00:00:00 2001 From: "Jiefeng Chen (WICRESOFT NORTH AMERICA LTD)" Date: Fri, 27 May 2022 09:11:48 +0800 Subject: [PATCH 02/11] remove to the folder --- doc/{ => issues}/resolve_issues_effectively.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/{ => issues}/resolve_issues_effectively.md (100%) diff --git a/doc/resolve_issues_effectively.md b/doc/issues/resolve_issues_effectively.md similarity index 100% rename from doc/resolve_issues_effectively.md rename to doc/issues/resolve_issues_effectively.md From 87b112ff42adab616ca022a3706147503a085a58 Mon Sep 17 00:00:00 2001 From: "Jiefeng Chen (WICRESOFT NORTH AMERICA LTD)" Date: Fri, 27 May 2022 09:14:56 +0800 Subject: [PATCH 03/11] remove to the folder --- doc/{ => dev}/issues/resolve_issues_effectively.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/{ => dev}/issues/resolve_issues_effectively.md (100%) diff --git a/doc/issues/resolve_issues_effectively.md b/doc/dev/issues/resolve_issues_effectively.md similarity index 100% rename from doc/issues/resolve_issues_effectively.md rename to doc/dev/issues/resolve_issues_effectively.md From ad909e33ed880385c5dc61daee357c6df991fed3 Mon Sep 17 00:00:00 2001 From: "Jiefeng Chen (WICRESOFT NORTH AMERICA LTD)" Date: Mon, 30 May 2022 17:36:58 +0800 Subject: [PATCH 04/11] add common error soluation --- doc/dev/issues/resolve_issues_effectively.md | 23 +++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/doc/dev/issues/resolve_issues_effectively.md b/doc/dev/issues/resolve_issues_effectively.md index 4e15b57ae7fa..a37143bf5344 100644 --- a/doc/dev/issues/resolve_issues_effectively.md +++ b/doc/dev/issues/resolve_issues_effectively.md @@ -11,6 +11,8 @@ Most issues can be classified into 3 categories. They are ## Usage error (For users) If you are not familiar with the SDK usage of a service, you can find relevant examples in [this repo][sample repo] in most cases. +For some common errors, you can check [here](#Summary Of Common Errors). + ## Feature Request(For users) See [here][request_a_feature] for more details. @@ -23,6 +25,23 @@ If you can provide detailed reproduction steps, it will help us locate and solve
+## Summary Of Common Errors + +### Error from track1 to track2 +If the code you use needs to set wait() function for the Long Running Operation to wait for the result, it should be the SDK of Track1. We have stopped maintenance at present. + +We strongly recommend that you update the SDK version. Then you will find that in the SDK of Track2, we all use the function name prefixed with `begin_` for LRO operations, and the result() method can be used to get the returned result. + +### Error from Service +Since the python SDK is generated based on the rest API, we will not deliberately change the returned results. So if you have any questions about the value of the response result of the request, please open the issue under the [rest issue][rest issue]. + +### Error like (AttributeError: 'PipelineResponse' object has no attribute 'get') +When this error occurs, you can check the version of `msrest`. Currently, for most SDKs, it needs to be >= 0.6.21. FYI: [SDK dependency][SDK dependency] + +You could upgrade the dependency before using the SDK to check if the issue has been solved. + +
+ ## Resolve issue (For contributors) Bug report is one of the most common issues reported in open-source community. Basic steps to resolve a bug report are @@ -56,4 +75,6 @@ If the issue is not from the SDK but from the [rest API][rest API], you can repl [sample repo]: https://github.com/Azure-Samples/azure-samples-python-management [request_a_feature]: https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/how_to_request_a_feature_in_sdk.md -[rest API]: https://github.com/Azure/azure-rest-api-specs \ No newline at end of file +[rest API]: https://github.com/Azure/azure-rest-api-specs +[rest issue]: https://github.com/Azure/azure-rest-api-specs/issues +[SDK dependency]: https://github.com/Azure/azure-sdk-for-python/blob/main/shared_requirements.txt From cfc40971ba6b791545bc291057e36fcba7a6cd63 Mon Sep 17 00:00:00 2001 From: Jiefeng Chen <51037443+BigCat20196@users.noreply.github.com> Date: Mon, 30 May 2022 17:44:12 +0800 Subject: [PATCH 05/11] Update resolve_issues_effectively.md --- doc/dev/issues/resolve_issues_effectively.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/dev/issues/resolve_issues_effectively.md b/doc/dev/issues/resolve_issues_effectively.md index a37143bf5344..07e699629dcc 100644 --- a/doc/dev/issues/resolve_issues_effectively.md +++ b/doc/dev/issues/resolve_issues_effectively.md @@ -27,13 +27,13 @@ If you can provide detailed reproduction steps, it will help us locate and solve ## Summary Of Common Errors -### Error from track1 to track2 +### Error from Track1 to Track2 If the code you use needs to set wait() function for the Long Running Operation to wait for the result, it should be the SDK of Track1. We have stopped maintenance at present. We strongly recommend that you update the SDK version. Then you will find that in the SDK of Track2, we all use the function name prefixed with `begin_` for LRO operations, and the result() method can be used to get the returned result. ### Error from Service -Since the python SDK is generated based on the rest API, we will not deliberately change the returned results. So if you have any questions about the value of the response result of the request, please open the issue under the [rest issue][rest issue]. +Since the python SDK is generated based on the [rest API][rest API], it will not deliberately change the returned results. So if you have any questions about the response result value of the request, please open the issue under the [rest issue][rest issue]. ### Error like (AttributeError: 'PipelineResponse' object has no attribute 'get') When this error occurs, you can check the version of `msrest`. Currently, for most SDKs, it needs to be >= 0.6.21. FYI: [SDK dependency][SDK dependency] From 2091c110402ad7ccb07f1f2cd9490a8e16c230a4 Mon Sep 17 00:00:00 2001 From: Yuchao Yan Date: Tue, 31 May 2022 08:50:15 +0800 Subject: [PATCH 06/11] Update doc/dev/issues/resolve_issues_effectively.md --- doc/dev/issues/resolve_issues_effectively.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/dev/issues/resolve_issues_effectively.md b/doc/dev/issues/resolve_issues_effectively.md index 07e699629dcc..0149e2420653 100644 --- a/doc/dev/issues/resolve_issues_effectively.md +++ b/doc/dev/issues/resolve_issues_effectively.md @@ -11,7 +11,7 @@ Most issues can be classified into 3 categories. They are ## Usage error (For users) If you are not familiar with the SDK usage of a service, you can find relevant examples in [this repo][sample repo] in most cases. -For some common errors, you can check [here](#Summary Of Common Errors). +For some common errors, you can check [here](##Summary Of Common Errors). ## Feature Request(For users) From 074e1ab46922195aa29085d64389463a1462f290 Mon Sep 17 00:00:00 2001 From: Yuchao Yan Date: Tue, 31 May 2022 08:51:14 +0800 Subject: [PATCH 07/11] Update doc/dev/issues/resolve_issues_effectively.md --- doc/dev/issues/resolve_issues_effectively.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/dev/issues/resolve_issues_effectively.md b/doc/dev/issues/resolve_issues_effectively.md index 0149e2420653..bd6e2a6c0709 100644 --- a/doc/dev/issues/resolve_issues_effectively.md +++ b/doc/dev/issues/resolve_issues_effectively.md @@ -11,7 +11,7 @@ Most issues can be classified into 3 categories. They are ## Usage error (For users) If you are not familiar with the SDK usage of a service, you can find relevant examples in [this repo][sample repo] in most cases. -For some common errors, you can check [here](##Summary Of Common Errors). +For some common errors, you can check [here](## Summary Of Common Errors). ## Feature Request(For users) From 921bc8542f508320e7af38e89c4f186217bce44c Mon Sep 17 00:00:00 2001 From: Jiefeng Chen <51037443+BigCat20196@users.noreply.github.com> Date: Tue, 31 May 2022 10:26:30 +0800 Subject: [PATCH 08/11] Update doc/dev/issues/resolve_issues_effectively.md Co-authored-by: Yuchao Yan --- doc/dev/issues/resolve_issues_effectively.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/dev/issues/resolve_issues_effectively.md b/doc/dev/issues/resolve_issues_effectively.md index bd6e2a6c0709..07156a23fcf7 100644 --- a/doc/dev/issues/resolve_issues_effectively.md +++ b/doc/dev/issues/resolve_issues_effectively.md @@ -36,9 +36,7 @@ We strongly recommend that you update the SDK version. Then you will find that i Since the python SDK is generated based on the [rest API][rest API], it will not deliberately change the returned results. So if you have any questions about the response result value of the request, please open the issue under the [rest issue][rest issue]. ### Error like (AttributeError: 'PipelineResponse' object has no attribute 'get') -When this error occurs, you can check the version of `msrest`. Currently, for most SDKs, it needs to be >= 0.6.21. FYI: [SDK dependency][SDK dependency] - -You could upgrade the dependency before using the SDK to check if the issue has been solved. +When this error occurs, you can check the version of `msrest` and upgrade it to latest version then try again.
From c7934e4e365cc7b3802059cf63e56746d30090da Mon Sep 17 00:00:00 2001 From: Jiefeng Chen <51037443+BigCat20196@users.noreply.github.com> Date: Tue, 31 May 2022 10:27:32 +0800 Subject: [PATCH 09/11] Update doc/dev/issues/resolve_issues_effectively.md Co-authored-by: Yuchao Yan --- doc/dev/issues/resolve_issues_effectively.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/dev/issues/resolve_issues_effectively.md b/doc/dev/issues/resolve_issues_effectively.md index 07156a23fcf7..209db2e012cd 100644 --- a/doc/dev/issues/resolve_issues_effectively.md +++ b/doc/dev/issues/resolve_issues_effectively.md @@ -32,7 +32,7 @@ If the code you use needs to set wait() function for the Long Running Operation We strongly recommend that you update the SDK version. Then you will find that in the SDK of Track2, we all use the function name prefixed with `begin_` for LRO operations, and the result() method can be used to get the returned result. -### Error from Service +### Possible Error from Service Since the python SDK is generated based on the [rest API][rest API], it will not deliberately change the returned results. So if you have any questions about the response result value of the request, please open the issue under the [rest issue][rest issue]. ### Error like (AttributeError: 'PipelineResponse' object has no attribute 'get') From 78b73f70a49d6515c7cbd02c521536debae48953 Mon Sep 17 00:00:00 2001 From: "Jiefeng Chen (WICRESOFT NORTH AMERICA LTD)" Date: Tue, 31 May 2022 10:44:43 +0800 Subject: [PATCH 10/11] update doc --- doc/dev/issues/resolve_issues_effectively.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/doc/dev/issues/resolve_issues_effectively.md b/doc/dev/issues/resolve_issues_effectively.md index 209db2e012cd..eccfb3e698b6 100644 --- a/doc/dev/issues/resolve_issues_effectively.md +++ b/doc/dev/issues/resolve_issues_effectively.md @@ -11,7 +11,7 @@ Most issues can be classified into 3 categories. They are ## Usage error (For users) If you are not familiar with the SDK usage of a service, you can find relevant examples in [this repo][sample repo] in most cases. -For some common errors, you can check [here](## Summary Of Common Errors). +For some common errors, you can check [here](#Summary Of Common Errors). ## Feature Request(For users) @@ -31,12 +31,10 @@ If you can provide detailed reproduction steps, it will help us locate and solve If the code you use needs to set wait() function for the Long Running Operation to wait for the result, it should be the SDK of Track1. We have stopped maintenance at present. We strongly recommend that you update the SDK version. Then you will find that in the SDK of Track2, we all use the function name prefixed with `begin_` for LRO operations, and the result() method can be used to get the returned result. +(More Details: [guidance][guidance]) ### Possible Error from Service -Since the python SDK is generated based on the [rest API][rest API], it will not deliberately change the returned results. So if you have any questions about the response result value of the request, please open the issue under the [rest issue][rest issue]. - -### Error like (AttributeError: 'PipelineResponse' object has no attribute 'get') -When this error occurs, you can check the version of `msrest` and upgrade it to latest version then try again. +Since the python SDK is generated based on the [rest API][rest API], it will not deliberately change the returned results. So if you think the returned result is not as expected, please open the issue under the [rest issue][rest issue].
@@ -70,9 +68,13 @@ Once you have confirmed the bug and found the fault location, it should be easy If the issue is not from the SDK but from the [rest API][rest API], you can reply to the user and reopen the issue in the appropriate place. +### Error like (AttributeError: 'PipelineResponse' object has no attribute 'get') +When this error occurs, you can check the version of `msrest` and upgrade it to latest version then try again. + [sample repo]: https://github.com/Azure-Samples/azure-samples-python-management [request_a_feature]: https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/how_to_request_a_feature_in_sdk.md [rest API]: https://github.com/Azure/azure-rest-api-specs [rest issue]: https://github.com/Azure/azure-rest-api-specs/issues [SDK dependency]: https://github.com/Azure/azure-sdk-for-python/blob/main/shared_requirements.txt +[guidance]: https://devblogs.microsoft.com/azure-sdk/migrating-python-management-libraries/ From faf419804a3a629e01b75a9e50a19d46024037bd Mon Sep 17 00:00:00 2001 From: Jiefeng Chen <51037443+BigCat20196@users.noreply.github.com> Date: Thu, 2 Jun 2022 10:37:28 +0800 Subject: [PATCH 11/11] Update resolve_issues_effectively.md --- doc/dev/issues/resolve_issues_effectively.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/dev/issues/resolve_issues_effectively.md b/doc/dev/issues/resolve_issues_effectively.md index eccfb3e698b6..a014681e9200 100644 --- a/doc/dev/issues/resolve_issues_effectively.md +++ b/doc/dev/issues/resolve_issues_effectively.md @@ -11,7 +11,7 @@ Most issues can be classified into 3 categories. They are ## Usage error (For users) If you are not familiar with the SDK usage of a service, you can find relevant examples in [this repo][sample repo] in most cases. -For some common errors, you can check [here](#Summary Of Common Errors). +For some common errors, you can check [here](#Summary-Of-Common-Errors). ## Feature Request(For users)