search

Azure / azure-sdk-tools

Tools repository leveraged by the Azure SDK team.
MIT License
114 stars 180 forks source link

Optimize docs for SDK pull request (data plane) #8178

Open ladonnaq opened 7 months ago

ladonnaq commented 7 months ago

Requirement: Optimize & seamlessly integrate processes, tools, & docs for SDK pull request.

Why? Survey results and direct feedback from Service Teams indicate a need to provide consistent standardized documentation regarding the SDK pull request process. Also, SDK team has indicated that there time is randomized by request to review & merge PRs that may not need to reviewed & approved by the SDK team. (i.e. Krzysztof Cwalina has brought this concern forward.)

Krzysztof Cwalina's feedback: Service partners tend to reach out to the Arch Board members regarding the process for review, approval, and merge of the SDK PRs. The SDK PRs are associated with the "High Level Client" and the "Generated SDK code + convenience layer". They also get asked questions about testing and samples that means it is not easily discovered by the users.

History: The Release Planner MVP is a self-service tool for generated SDKs only. The current SDK release milestone (process workflow) does not include tasks associated with the convenience layer or minor changes to generated code that is almost always required for data plane SDKs by the Arch Board.

Selenium Plans:

  1. Language PMs lead doc review of the SDK PR process for their language. Target completion by December 05, 2024.

    • [ ] .NET SDK PR doc review
    • [ ] Java SDK PR doc review
    • [ ] JavaScript SDK PR doc review
    • [ ] Python SDK PR doc review
    • [ ] Go SDK PR doc review

  2. Language PMs collaborate with language engineering lead to update the docs in the repos. Target completion by December 10, 2024. Based on Service Partner feedback the preference format is to use DO & DO NOT (similar to API Spec & SDK guidelines). The Java and JS docs are already in this format.

    • [ ] .NET SDK PR docs updated
    • [ ] Java SDK PR docs updated
    • [ ] JavaScript SDK PR docs updated
    • [ ] Python SDK PR docs updated
    • [ ] Go SDK PR docs updated

  3. Contribute and review the consolidated guidance that will be published on our engineering hub site. Target completion by December 15, 2024.

    • [ ] Consolidated doc for engineering hub

Please find the latest documentation below:

Future (beyond Selenium)

### Related GitHub issues 
- [ ] https://github.com/Azure/azure-sdk-for-net/pull/45971
- [ ] https://github.com/Azure/azure-sdk-tools/issues/8972
maririos commented 6 months ago

An example of things we need to cover here is how our users should think/use the test infrastructure. We want to make sure this information is surfaced in the right places so users can find it. https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/389/Configuring-Tests

ladonnaq commented 6 months ago

An example of things we need to cover here is how our users should think/use the test infrastructure. We want to make sure this information is surfaced in the right places so users can find it. https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/389/Configuring-Tests

@ronniegeraghty - I am adding you as an assignee as well. This is the issue we are using to track the docs for guidance on the SDK PR process, including testing, samples, etc.

ronniegeraghty commented 6 months ago

I spoke with Krzysztof. He mentioned that he'd like more documentation around both our PR process and the Arch Board Review meetings. Simply, for PR's he'd like our partner teams to have a better understanding of who they should be working with during the PR process. Eng Leads/ Senior Engs for code reviews, Eng Sys for understanding pipeline failures, and if languages have a specific process they'd like to use. For the Arch Board, he'd like our partner teams to have a better understanding of what type of agenda they should expect depending on the type of Arch Board meeting they scheduled. Examples of meeting types: Intro (Teams first time meeting the Arch Board), Brand New libraries (new service libraries), Preview release (new features), GA release, (following up from preview release where new features were introduced, or minor change that is going straight to GA).

maririos commented 5 months ago

This issue should also cover which APIViews they should use for approval, and how to request that approval (let's say after an archboard happened and the user addressed the feedback, then they need approval but not neccesarily a meeting)

ladonnaq commented 5 months ago

@ronniegeraghty - Can you add links to all of the documentation and the author(s)/owner(s)?

ronniegeraghty commented 5 months ago

And the authors would be the different language leads. And if they want to delegate it they can.

maririos commented 2 months ago

And the authors would be the different language leads. And if they want to delegate it they can.

I just saw this. This is great. I created issue #8972 to see how/where should we add this information in the release planner and our eng hub docs

ladonnaq commented 2 weeks ago

And the authors would be the different language leads. And if they want to delegate it they can.

I just saw this. This is great. I created issue #8972 to see how/where should we add this information in the release planner and our eng hub docs

Who owns the todo for Python? Would that be Rohit and Laurent?