Azure / Azure/azure-sdk-tools

Updates to APEX requirements and release plan docs

Open
#7,558 2 comments 0 reactions 1 assignee Assigned to @jrferry101 View on GitHub
Engagement Experience
Dominant language
C#
Stars
135
Forks
260
Avg merge
3d 1h
Merged PRs (30d)
143

Description

**Requirement:** Update APEX requirement and release plan docs based on stakeholder and service partner feedback

**Topics to be covered in revised docs**

- Release Planner Overview
- Onboard a service & product to the SDK system
- What is a release plan?
- Personas (Eng & PM) and release plans
- What are the APEX requirements for launching my new product for Private Preview, Public Preview, & GA based on common scenarios

**Common scenarios highlight progression from Beta to Stable SDKs**

- Scenario 1: Service is not GA, External Product is not GA. Publish initial Preview API version -> Generate & release Beta SDKs (Preview API version) -> Publish initial Stable API version -> Generate & release Stable SDKs (Stable API version)

- Scenario 2: Service is GA, new external Product introducing significant changes to the existing RP & ARM REST APIs. Publish new Preview API version - > Generate & release Beta SDKs (Preview API version) -> Publish new Stable API version -> Generate & release Stable SDKs (Stable API version)

- Scenario 3: Service is GA, new product which is NOT introducing significant changes to existing RP and ARM REST APIs. Publish new Preview or Stable API version -> Generate & release Beta SDKs (Preview or Stable API version) -> Publish new Stable API version (if there are changes) -> Generate & release Stable SDKs (Stable API version)

```[tasklist]
### Tasks
- [x] Update all CLC APEX launch readiness requirement descriptions. Word doc versions can be found here - https://microsoft-my.sharepoint.com/:f:/p/ladonnaquinn/EtleLFJfcPtHkVKmzCry4EQBQ0jdnHeqewuWgtqeNdzihg?e=vpvmDw
- [x] Release Planner Overview for data & management plane presentations - https://microsoft-my.sharepoint.com/:p:/p/ladonnaquinn/EbLiwHt9anBJrSSdyquA5uAB-KH2FcjVBfoeAJkYdzWnvw?e=wpg0AT & https://microsoft-my.sharepoint.com/:p:/p/ladonnaquinn/EfqXO1e8btpBtPD4R7G8hLAB5BX35ILcdQSMRQ3vGTuYaQ?e=5sM0tm
- [ ] Create and link to demos that cover Release Planner overview, data plane milestone overview for Public Preview, management plane milestone overview for Public Preview
- [x] Provide guidance on new initial vs new SDK versions requirements to help teams navigate the release plans until they are customized based on the scenario. Diagrams are in the release planner overview presentations.
- [ ] Create example release plans in PPE for Private Preview
- [x] Create example release plans in PPE for Public Preview. Mgmt - https://web.powerapps.com/apps/8ca4408d-6af3-475f-90fe-51b2e43624bb?release-plan-id=6e891c96-942d-ef11-840a-000d3a9cab13 & Data - https://web.powerapps.com/apps/8ca4408d-6af3-475f-90fe-51b2e43624bb?release-plan-id=c3bf1b04-cec9-ee11-9079-000d3a565aab
- [ ] Create example release plan in PPE for GA
```

 

**Request from Catalinia based on service partner feedback:** @catalinaperalta

Hi all,

I wanted to reach out with a suggestion that I think will help with Release Planner adoption. I’ve noticed that a few service teams seem to be reluctant to begin working with the release planner and usually their questions are related to what information/commitments will be expected of them once they create one. I think having documentation in engineering hub with a step by step tutorial with screenshots of each of the release plan pages would be helpful since some service partners would like to know beforehand what to expect from the app from start to finish. I have seen the diagram we currently have on the site, but I believe a step-by-step tutorial would be even more intuitive and would show service partners what information the app will request from them. This could additionally be done in a video format if we think that would be easier for some folks to learn how to use the release planner.

Here is a quote I got in email today from the Health Insights team about using the release planner: “Is there a tutorial regarding how to complete/use the planner ?”

It would also be good to emphasize that the app is meant to be used by both PMs and developers since I have found that to also be a point of confusion. Highlighting how this app helps/benefits each team member through the process would be helpful and we can start pointing folks to these specific documentation sections to encourage adoption and improve usage.

Let me know if you have any questions or if I can provide any more information.
Thanks,
Catalina

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.