Skip to content

Commit 9afe19c

Browse files
tianzhoutianzhou
committed
docs: release/review/plan/rollout api
1 parent 2a0ddb7 commit 9afe19c

File tree

5 files changed

+103
-63
lines changed

5 files changed

+103
-63
lines changed

‎content/docs/_layout.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -243,6 +243,12 @@ expand_section_list: ['Self-host']
243243

244244
### [SQL Review](/docs/api/sql-review)
245245

246+
### [Release](/docs/api/release)
247+
248+
### [Plan](/docs/api/plan)
249+
250+
### [Rollout](/docs/api/rollout)
251+
246252
### [Issue](/docs/api/issue)
247253

248254
### [SQL Editor](/docs/api/sql-editor)

‎content/docs/api/issue.md‎

Lines changed: 9 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,21 @@ title: Issue
44

55
<TutorialBlock url="/docs/tutorials/api-issue" title="Create Issue with Bytebase API" />
66

7-
| | |
8-
| --------------- | --------------------------------------------- |
9-
| Issue Service | https://api.bytebase.com/#/tag/issueservice |
10-
| Plan Service | https://api.bytebase.com/#/tag/planservice |
11-
| Rollout Service | https://api.bytebase.com/#/tag/rolloutservice |
12-
| Sheet Service | https://api.bytebase.com/#/tag/sheetservice |
7+
| | |
8+
| ------------- | ------------------------------------------- |
9+
| Issue Service | https://api.bytebase.com/#/tag/issueservice |
1310

1411
`Issue` drives the database operations in Bytebase. The issue contains following info:
1512

1613
- **Issue metadata.** e.g `title` and `description`.
17-
- **Plan.** Contain one or multiple SQL statements and dictate how they are grouped and ordered. The plan layouts how to execute the SQL statements.
18-
- **Sheet**. Plan references SQL statements via the `Sheet` object. Each `Sheet` contains one or more SQL statements.
14+
- **Plan.** Contain one or multiple change statements and dictate how they are grouped and ordered. The plan layouts how to execute the change statements.
15+
- **Sheet**. Plan references change statements via the `Sheet` object. Each `Sheet` contains one or more change statements.
1916
- **Step**. Plan orchestrates the order via `Step`. Each `Step` specifies one or more changes units. A change unit specifies the SQL statements via `Sheet` and the target database.
2017
- **Rollout.** The actual execution of the plan.
2118

2219
## How to create an issue
2320

24-
Code sample: https://github.com/bytebase/cicd-github-actions-example/blob/main/.github/actions/upsert-issue/index.ts#L68-L75
21+
Code sample: https://github.com/bytebase/upsert-issue-action/blob/main/src/main.ts#L86-L92
2522

2623
```go
2724
// Create plan
@@ -36,61 +33,10 @@ issue = await createIssue(plan.name, rollout.name, title, description);
3633

3734
### Step 1: Create a plan.
3835

39-
Inside the plan, create one or more sheets if needed. Then you orchestrate the order via Steps:
40-
41-
```json
42-
{
43-
"steps": [
44-
{
45-
"title": "step 1",
46-
"specs": [
47-
{
48-
"earliestAllowedTime": null,
49-
"id": "083c1c01-a0a6-485d-ae60-d6de2760ca4f",
50-
"dependsOnSpecs": [],
51-
"changeDatabaseConfig": {
52-
"target": "instances/oracle/databases/db1",
53-
"sheet": "projects/sample/sheets/741",
54-
"type": "MIGRATE",
55-
"schemaVersion": "",
56-
"ghostFlags": {},
57-
"preUpdateBackupDetail": {
58-
"database": ""
59-
}
60-
}
61-
},
62-
{
63-
"earliestAllowedTime": null,
64-
"id": "faa54bb9-0bb3-42bf-aa10-cffc73e19e33",
65-
// Wait for the previous task to finish
66-
"dependsOnSpecs": ["083c1c01-a0a6-485d-ae60-d6de2760ca4f"],
67-
"changeDatabaseConfig": {
68-
"target": "instances/oracle/databases/db1",
69-
"sheet": "projects/sample/sheets/742",
70-
"type": "MIGRATE",
71-
"schemaVersion": "",
72-
"ghostFlags": {},
73-
"preUpdateBackupDetail": {
74-
"database": ""
75-
}
76-
}
77-
}
78-
]
79-
},
80-
{
81-
"title": "step 2",
82-
"specs": [{...}, {...}]
83-
}
84-
]
85-
}
86-
```
87-
88-
Each spec corresponds to a task. A task is a single change unit. Tasks run in the following order:
89-
90-
<IncludeBlock url="/docs/share/tutorials/task-run-order"></IncludeBlock>
91-
92-
If you want to enforce strict running order inside a step/stage. You can specify `dependsOnSpecs` with the previous task.
36+
See [Plan API](/docs/api/plan).
9337

9438
### Step 2: Create a rollout for the plan
9539

40+
See [Rollout API](/docs/api/rollout).
41+
9642
### Step 3: Create an issue including both the plan and the rollout

‎content/docs/api/plan.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: Plan
3+
---
4+
5+
| | |
6+
| ------------- | ------------------------------------------- |
7+
| Plan Service | https://api.bytebase.com/#/tag/planservice |
8+
| Sheet Service | https://api.bytebase.com/#/tag/sheetservice |
9+
10+
`Plan` contains one or multiple change statements and dictate how they are grouped and ordered. The plan layouts how to execute the change statements.
11+
12+
- **Sheet**. Plan references change statements via the `Sheet` object. Each `Sheet` contains one or more change statements.
13+
- **Step**. Plan orchestrates the order via `Step`. Each `Step` specifies one or more changes units. A change unit specifies the SQL statements via `Sheet` and the target database.
14+
15+
Code sample: https://github.com/bytebase/create-plan-from-release-action/blob/main/src/main.ts
16+
17+
Inside the plan, create one or more sheets if needed. Then you orchestrate the order via Steps:
18+
19+
```json
20+
{
21+
"steps": [
22+
{
23+
"title": "step 1",
24+
"specs": [
25+
{
26+
"earliestAllowedTime": null,
27+
"id": "083c1c01-a0a6-485d-ae60-d6de2760ca4f",
28+
"dependsOnSpecs": [],
29+
"changeDatabaseConfig": {
30+
"target": "instances/oracle/databases/db1",
31+
"sheet": "projects/sample/sheets/741",
32+
"type": "MIGRATE",
33+
"schemaVersion": "",
34+
"ghostFlags": {},
35+
"preUpdateBackupDetail": {
36+
"database": ""
37+
}
38+
}
39+
},
40+
{
41+
"earliestAllowedTime": null,
42+
"id": "faa54bb9-0bb3-42bf-aa10-cffc73e19e33",
43+
// Wait for the previous task to finish
44+
"dependsOnSpecs": ["083c1c01-a0a6-485d-ae60-d6de2760ca4f"],
45+
"changeDatabaseConfig": {
46+
"target": "instances/oracle/databases/db1",
47+
"sheet": "projects/sample/sheets/742",
48+
"type": "MIGRATE",
49+
"schemaVersion": "",
50+
"ghostFlags": {},
51+
"preUpdateBackupDetail": {
52+
"database": ""
53+
}
54+
}
55+
}
56+
]
57+
},
58+
{
59+
"title": "step 2",
60+
"specs": [{...}, {...}]
61+
}
62+
]
63+
}
64+
```
65+
66+
Each spec corresponds to a task. A task is a single change unit. Tasks run in the following order:
67+
68+
<IncludeBlock url="/docs/share/tutorials/task-run-order"></IncludeBlock>
69+
70+
If you want to enforce strict running order inside a step/stage. You can specify `dependsOnSpecs` with the previous task.

‎content/docs/api/release.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: Release
3+
---
4+
5+
| | |
6+
| --------------- | --------------------------------------------- |
7+
| Release Service | https://api.bytebase.com/#/tag/releaseservice |
8+
9+
Sample repository https://github.com/bytebase/create-release-action/blob/main/src/main.ts

‎content/docs/api/rollout.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: Rollout
3+
---
4+
5+
| | |
6+
| --------------- | --------------------------------------------- |
7+
| Rollout Service | https://api.bytebase.com/#/tag/rolloutservice |
8+
9+
Code sample: https://github.com/bytebase/rollout-action/blob/main/src/main.ts

0 commit comments

Comments
 (0)