Skip to content

Commit 719eeab

Browse files
raych1weshaggard
raych1
and
weshaggard
authored
Updated common script part in typespec e2e doc (#23875)
* Updated common script part in typespec e2e doc * Update documentation/typespec-end-to-end-scenarios.md Co-authored-by: Wes Haggard <[email protected]> * Update documentation/typespec-end-to-end-scenarios.md Co-authored-by: Wes Haggard <[email protected]> * Resolve comments * Refactor the content * Update bulletin --------- Co-authored-by: Wes Haggard <[email protected]>
1 parent e6c0e18 commit 719eeab

File tree

1 file changed

+83
-70
lines changed

1 file changed

+83
-70
lines changed

‎documentation/typespec-end-to-end-scenarios.md

Lines changed: 83 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -4,22 +4,30 @@
44

55
It is crucial having simple and smooth processes that allow developer to easily:
66

7-
1. [Scaffolding TypeSpec project in `rest-api-specs` repo](#1-typespec-project-scaffolding)
8-
2. [SDK code generation in SDK repos](#2-sdk-code-generation)
9-
1. All SDK required information (SDK path, namespace etc) should be set in `tspconfig.yaml`.
10-
2. Single call via `eng/scripts` in each language repo to complete the task
11-
3. Optional, intelligent CI pipeline component to create related PRs when a new service API PR is submitted.
12-
3. [TypeSpec inner dev loop](#3-inner-dev-loop-sdk-generation-local-scenario)
13-
1. For spec writers:
14-
1. locally preview generated Swagger file
15-
2. gather relevant files to generate rest-api-spec PRs with green CI results
16-
2. For SDK writers or testing
17-
1. locally preview generated SDK files
18-
2. generating SDK PRs from checked in TypeSpec files in rest-api-spec with APIView
19-
3. any CI failures can be reproduced locally
20-
4. [Typespec outer dev loop `rest-api-specs`](#4-outer-loop-overall-status-and-tracking).
21-
1. [Spec repo outer dev loop](#41-outer-dev-loop-azure-rest-api-specs-pipeline)
22-
2. [SDK outer dev loop](#42-outer-dev-loop-sdk-repo-pipeline)
7+
- [TypeSpec end to end scenarios](#typespec-end-to-end-scenarios)
8+
- [Scenario definitions](#scenario-definitions)
9+
- [Four main user scenarios to support](#four-main-user-scenarios-to-support)
10+
- [1. TypeSpec project scaffolding](#1-typespec-project-scaffolding)
11+
- [Flowchart](#flowchart)
12+
- [Remaining Tasks](#remaining-tasks)
13+
- [Details \& Open questions](#details--open-questions)
14+
- [2. SDK code generation](#2-sdk-code-generation)
15+
- [Flowchart](#flowchart-1)
16+
- [Remaining Tasks](#remaining-tasks-1)
17+
- [3. Inner Dev loop SDK generation local scenario](#3-inner-dev-loop-sdk-generation-local-scenario)
18+
- [Flowchart](#flowchart-2)
19+
- [Remaining Tasks](#remaining-tasks-2)
20+
- [Details \& Open questions](#details--open-questions-1)
21+
- [4.Dev Outer loop](#4dev-outer-loop)
22+
- [Use case](#use-case)
23+
- [4.1 Outer Dev loop azure-rest-api-specs pipeline](#41-outer-dev-loop-azure-rest-api-specs-pipeline)
24+
- [Flowchart](#flowchart-3)
25+
- [Details \& Open questions](#details--open-questions-2)
26+
- [4.2 Outer Dev loop SDK repo pipeline](#42-outer-dev-loop-sdk-repo-pipeline)
27+
- [Flowchart](#flowchart-4)
28+
- [Details \& Open questions](#details--open-questions-3)
29+
- [4. Outer loop Overall Status and tracking](#4-outer-loop-overall-status-and-tracking)
30+
- [Remaining Tasks](#remaining-tasks-3)
2331

2432
Aside from the developer process, we have a few goals on managing repo package version
2533
- Should adopt a centralized package version control to avoid chaos
@@ -68,57 +76,71 @@ classDef grey fill:#CCCCCC,color:#555555;
6876
User((::))-->A
6977
A["clone Rest-API and SDK repo locally"] --> B
7078
B["2.1 pre-requsite dependencies installation
71-
(each language would have a installation script)"] --> C
72-
C["2.2 TypeSpec-Project-Sync.ps1
73-
(a.create tsp-location.yaml and drop to temp location
74-
b.update tsp-location.yaml if existed
75-
c.fetch specs from remote spec repo or use local spec repo)"] --> D
76-
D["2.3 TypeSpec-Project-Generate.ps1
77-
(a.create scaffolding for new project
78-
b.update tsp-location.yaml
79-
c.copy typespec specs to temp folder
80-
d.generate sdk code)"]
81-
D-->E["code build"]
79+
(each language would have a installation script)"] --> G
80+
subgraph G["run `2.2 TypeSpec-Project-Prcoess.ps1`"]
81+
F
82+
C
83+
D
84+
end
85+
F["2.2.1 create/update tsp-location.yaml"]
86+
C["2.2.2 call TypeSpec-Project-Sync.ps1"]
87+
D["2.2.3 call TypeSpec-Project-Generate.ps1"]
88+
G-->E["code build"]
8289
class A,E grey
83-
class C,D highlight
90+
class C,D,F highlight
8491
```
85-
- 2.2 `TypeSpec-Project-Sync.ps1`
86-
- input:
87-
- sdkProjectDirectory
88-
- typespecProjectDirectory
89-
- repo
90-
- commit
91-
- additionalDirectories
92-
- localMode (use local spec and don't fetch from remote)
93-
- localSpecRepoPath
94-
Note: we might pull out tsp-location.yaml create/update part as single script to be used by #2 scenario
95-
- output:
96-
- path of sdkProjectDirectory
92+
- 2.1 Optional: Scripts should exist under `\eng\scripts\` folder on all repos.
9793

98-
- Function `Get-{Language}-Tsp-Location-Path`
99-
- input: sdkProjectDirectory
100-
- output: path of tsp-location.yaml
94+
- 2.2 `TypeSpec-Project-Process.ps1`
95+
- What does this script do?
96+
- fetch `tspconfig.yaml` from remote if it doesn’t exist locally
97+
- parse `tspconfig.yaml`
98+
- create an sdk project folder if none exists
99+
- create/update `tsp-location.yaml`
100+
- call `TypeSpec-Project-Sync.ps1`
101+
- call `TypeSpec-Project-Generate.ps1`
102+
- input:
103+
- typespecProjectDirectory (required)
104+
either a folder of `tspconfig.yaml` or a remoteUrl of `tspconfig.yaml`
105+
- commitSha (optional)
106+
- repoUrl (optional)
107+
- output: n/a
101108

102-
- 2.3 `TypeSpec-Project-Generate.ps1`
103-
- input:
104-
- projectDirectory
105-
- typespecAdditionalOptions (emitter options)
109+
- 2.2.2 `TypeSpec-Project-Sync.ps1`
110+
- What does this script do?
111+
- fetch specs from remote spec repo or use a local spec repo
112+
- copy specs to temp location under the sdk project folder
113+
- support a local spec repo if one exists (TODO)
114+
- input:
115+
- projectDirectory (required)
116+
- localSpecRepoPath (optional)
117+
- output: n/a
106118

107-
- Function `Generate-{Language}-New-Project-Scaffolding`
108-
- input: path of tsp-location.yaml
119+
- 2.2.3 `TypeSpec-Project-Generate.ps1`
120+
- What does this script do?
121+
- create scaffolding for new project (use the folder created by 2.2)
122+
- generate sdk code
123+
- input:
124+
- projectDirectory (required)
125+
- typespecAdditionalOptions (emitter options) (optional)
126+
127+
- 2.2.3.1 Function `Generate-{Language}-New-Project-Scaffolding`
128+
- What does this function do?
129+
- Create the folders and the files under SDK project folder, such as creating `test` folder, `sln` files that would vary between language repos. Eventually, this project scaffolding would be integrated into language emitter.
130+
- Create or update the files outside of the SDK project folder (CI.yml or pom.xml for java, etc.)
131+
- This function is called by generate script(2.4)
132+
- input: projectDirectory (required)
109133

110134
##### Remaining Tasks
111135
| Step | Step Detail | Assignee | Implemented | Verified |
112136
|--|--|--|--:|--:|
113137
| 2.1 | Dependencies scripts | SDK owner | [ ] | [] |
114-
| 2.2 | common script | EngSys | [ ] | | [ ] |
115-
| 2.3 | common script | EngSys | [ ] | | [ ] |
116-
| 2.4 | language script to call common script | SDK owner | [] | []
117-
| 2.5 | update to dotnet build target | Michael, Crystal | [] | []
118-
119-
##### Details & Open questions
120-
- 2.1 Optional: Scripts should exists under `\eng\scripts\` folder on all repos.
121-
- 2.2 would involve more than just creating folder and generate `tsp-location.yaml`. There are other custom steps such as creating `test` folder, `sln` files that would vary between language repos.
138+
| 2.2 | TypeSpec-Project-Process.ps1 | EngSys | [ ] | | [ ] |
139+
| 2.2.2 | TypeSpec-Project-Sync.ps1 | EngSys | [ ] | | [ ] |
140+
| 2.2.3 | TypeSpec-Project-Generate.ps1 | EngSys | [ ] | | [ ] |
141+
| 2.2.3.1 | Generate-{Language}-New-Project-Scaffolding | SDK owner | [ ] | | [ ] |
142+
| 2.3 | Language script to call common script | SDK owner | [] | []
143+
| 2.4 | Update dotnet build target | Michael, Crystal | [] | []
122144

123145
#### 3. Inner Dev loop SDK generation local scenario
124146
##### Flowchart
@@ -137,11 +159,10 @@ flowchart TD;
137159
F["docker run
138160
(a. call `initScript` - 2.1
139161
b. call `generateScript`
140-
(2.2 + 2.3) )"]-->I
162+
(call 2.2) )"]-->I
141163
D-->K
142164
K["optional:2.1"]-->G
143-
G["2.2"]-->H
144-
H["2.3"]-->I
165+
G["2.2"]-->I
145166
I["build code and work on test,sample,readme,etc."]-->J
146167
I-->|loop|B
147168
J["create sdk PR"]
@@ -195,10 +216,8 @@ C["run `initScript`
195216
(2.1)"]-->G
196217
subgraph D["run `generateScript`"]
197218
G
198-
H
199219
end
200-
G["2.2"]-->H
201-
H["2.3"]-->I
220+
G["2.2"]-->I
202221
I["package sdk code"]-->J
203222
J["optional:build code and run test"]-->K
204223
K["upload artifacts"]-->L
@@ -236,17 +255,11 @@ A["run `initScript`
236255
(2.1)"]-->C
237256
subgraph B["run `generateScript`"]
238257
C
239-
D
240258
E
241259
F
242260
G
243261
end
244-
C["2.2
245-
(a.use existing tsp-location.yaml
246-
b.fetch specs from remote spec repo
247-
c.then copy typespec specs to temp folder)"]-->D
248-
D["2.3
249-
(generate sdk code)"]-->E
262+
C["call 2.2"]-->E
250263
E["package sdk code"]-->F
251264
F["build code"]-->G
252265
G["run test"]

0 commit comments

Comments
 (0)