Skip to content

Commit 313f75b

Browse files
jippijippi
committed
docs: expand docs and style it proper
1 parent 6da781c commit 313f75b

File tree

9 files changed

+148
-144
lines changed

9 files changed

+148
-144
lines changed

‎.markdownlint.yml

+1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
MD046: false
22
MD013: false
3+
MD051: false

‎docs/_partials/expr-lang-info.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
!!! note "This field must be a valid [Expr lang](https://expr-lang.org/){target="_blank"} script"
2+
3+
Please see the following pages for more information:
4+
5+
* [Expr lang documentation](https://expr-lang.org/docs/language-definition){target="_blank"}
6+
* `scm-engine` [attributes](../gitlab/script-attributes.md), [functions](../gitlab/script-functions.md), and [examples](../configuration/examples.md)

‎docs/commands/sever.md ‎docs/commands/server.md

File renamed without changes.

‎docs/configuration/examples.md

+23-6
Original file line numberDiff line numberDiff line change
@@ -97,14 +97,31 @@ actions:
9797

9898
```yaml
9999
label:
100-
# Add a label named "lang/go"
101100
- name: lang/go
102-
# and a label description (optional)
103-
description: "Modified Go files"
104-
# and the color $indigo
105-
color: "$indigo"
106-
# if files matching "*.go" was modified
101+
color: $indigo
107102
script: merge_request.modified_files("*.go")
103+
104+
- name: lang/markdown
105+
color: $indigo
106+
script: merge_request.modified_files("*.md")
107+
108+
- name: type/documentation
109+
color: $green
110+
script: merge_request.modified_files("docs/")
111+
112+
- name: go::tests::missing
113+
color: $red
114+
priority: 999
115+
script: |1
116+
merge_request.modified_files("*.go")
117+
&& NOT merge_request.modified_files("*_test.go")
118+
119+
- name: go::tests::ok
120+
color: $green
121+
priority: 999
122+
script: |1
123+
merge_request.modified_files("*.go")
124+
&& merge_request.modified_files("*_test.go")
108125
```
109126

110127
=== "Script with highlight"

‎docs/configuration/index.md

+68-123
Original file line numberDiff line numberDiff line change
@@ -2,64 +2,76 @@
22

33
The default configuration filename is `.scm-engine.yml`, either in current working directory, or if you are in a Git repository, the root of the project.
44

5-
The file path can be changed via `--config` CLI flag and `$SCM_ENGINE_CONFIG_FILE` environment variable.
5+
The file path can be changed via `--config` CLI flag and `#!css $SCM_ENGINE_CONFIG_FILE` environment variable.
66

77
## `actions[]` {#actions data-toc-label="actions"}
88

9-
The `actions` key is a list of actions that can be taken on a Merge Request.
9+
!!! question "What are actions?"
10+
11+
Actions can [modify a Merge Request](#actions.if.then.action) in various ways, for example, adding a comment or closing the Merge Request.
12+
13+
Due to actions powerful and flexible capabilities, they can be a bit harder to get *right* than [adding and removing labels](#label).
14+
15+
Please see the [examples page](examples.md) for use-cases.
16+
17+
The `#!css actions` key is a list of actions that can be taken on a Merge Request.
1018

1119
### `actions[].name` {#actions.name data-toc-label="name"}
1220

13-
The name of the action, this is purely for debugging and your convenience. It's encouraged to be descriptive of the actions.
21+
The name of the action, this is purely for debugging and your convenience.
22+
23+
It's encouraged to be descriptive of the actions.
1424

1525
### `actions[].if` {#actions.if data-toc-label="if"}
1626

17-
A key controlling if the action should executed or not.
27+
--8<-- "docs/_partials/expr-lang-info.md"
28+
29+
!!! tip "The script must return a `#!css boolean`"
1830

19-
The `if` field must be a valid [Expr-lang](https://expr-lang.org/) expression returning a boolean.
31+
A key controlling if the action should executed or not.
2032

2133
### `actions[].if.then[]` {#actions.if.then data-toc-label="then"}
2234

23-
The list of operations to take if the `action.if` returned `true`.
35+
The list of operations to take if the [`#!css action.if`](#actions.if) returned `true`.
2436

2537
#### `actions[].if.then[].action` {#actions.if.then.action data-toc-label="action"}
2638

2739
This key controls what kind of action that should be taken.
2840

29-
- `close` to close the Merge Request.
30-
- `reopen` to reopen the Merge Request.
31-
- `lock_discussion` to prevent further discussions on the Merge Request.
32-
- `unlock_discussion` to allow discussions on the Merge Request.
33-
- `approve` to approve the Merge Request.
34-
- `unapprove` to approve the Merge Request.
35-
- `comment` to add a comment to the Merge Request
41+
- `#!yaml close` to close the Merge Request.
42+
- `#!yaml reopen` to reopen the Merge Request.
43+
- `#!yaml lock_discussion` to prevent further discussions on the Merge Request.
44+
- `#!yaml unlock_discussion` to allow discussions on the Merge Request.
45+
- `#!yaml approve` to approve the Merge Request.
46+
- `#!yaml unapprove` to approve the Merge Request.
47+
- `#!yaml comment` to add a comment to the Merge Request
3648

3749
*Additional fields:*
3850

39-
- (required) `message` The message that will be commented on the Merge Request.
51+
- (required) `#!css message` The message that will be commented on the Merge Request.
4052

4153
```{.yaml title="'comment' example"}
4254
- action: comment
4355
message: |
4456
Hello world
4557
```
4658

47-
- `add_label` to add *an existing* label to the Merge Request
59+
- `#!yaml add_label` to add *an existing* label to the Merge Request
4860

4961
*Additional fields:*
5062

51-
- (required) `label` The label name to add.
63+
- (required) `#!css label` The label name to add.
5264

5365
```{.yaml title="add_label example"}
5466
- action: add_label
5567
label: example
5668
```
5769

58-
- `remove_label` to remove a label from the Merge Request
70+
- `#!yaml remove_label` to remove a label from the Merge Request
5971

6072
*Additional fields:*
6173

62-
- (required) `label` The label name to add.
74+
- (required) `#!css label` The label name to add.
6375

6476
```{.yaml title="remove_label example"}
6577
- action: remove_label
@@ -68,152 +80,85 @@ This key controls what kind of action that should be taken.
6880

6981
## `label[]` {#label data-toc-label="label"}
7082

71-
The `label` key is a list of the labels you want to manage.
83+
!!! question "What are labels?"
7284

73-
These keys are shared between the `conditional` and `generate` label strategy. (more above these below!)
85+
Labels are a way to categorize and filter issues, merge requests, and epics in GitLab.
86+
-- *[GitLab documentation](https://docs.gitlab.com/ee/user/project/labels.html){target="_blank"}*
7487

75-
### `label[].name` {#label.name data-toc-label="name"}
88+
The `#!css label` key is a list of the labels you want to manage.
7689

77-
- When using `label.strategy: conditional`
90+
These keys are shared between the [`#!yaml conditional`](#label.strategy-conditional) and [`#!yaml generate`](#label.strategy-generate) label strategy. (more above these below!)
7891

79-
**REQUIRED** The `name` of the label to create.
92+
### `label[].strategy` {#label.strategy data-toc-label="strategy"}
8093

81-
- When using `label.strategy: generate`
94+
SCM Engine supports two strategies for managing labels, each changes the behavior of the [`#!css script`](#label.script).
8295

83-
**OMITTED** The `name` field must not be set when using the `generate` strategy.
96+
- `#!yaml conditional` (default, if `#!css strategy` key is omitted), where you provide the `#!css name` of the label, and a [`#!css script`](#label.script) that returns a boolean for wether the label should be added to the Merge Request.
8497

85-
### `label[].script` {#label.script data-toc-label="script"}
98+
The [`#!css script`](#label.script) must return a `#!yaml boolean` value, where `#!yaml true` mean `add the label` and `#!yaml false` mean `remove the label`.
8699

87-
!!! tip
100+
- `#!yaml generate`, where your `#!css script` generates the list of labels that should be added to the Merge Request.
88101

89-
See the [SCM engine expr-lang documentation](#expr-lang-information) for more information about [functions](#functions) and [attributes](#attributes) available.
102+
The [`#!css script`](#label.script) must return a `list of strings`, where each label returned will be added to the Merge Request.
90103

91-
The `script` field is an [expr-lang](https://expr-lang.org/) expression, a safe, fast, and intuitive expression evaluator.
104+
#### `label[].strategy = conditional` {#label.strategy-conditional data-toc-label="conditional"}
92105

93-
Depending on the `label.strategy` used, the behavior of the script changes, read more about this below.
106+
Use the `#!yaml conditional` strategy when you want to add/remove a label on a Merge Request depending on *something*. It's the default strategy, and the most simple one to use.
94107

95-
### `label[].strategy` {#label.strategy data-toc-label="strategy"}
108+
!!! example "Please see the [*Add label if a file extension is modified*](examples.md#add-label-if-a-file-extension-is-modified) example for how to use this"
96109

97-
SCM Engine supports two strategies for managing labels, each changes the behavior of the `script`.
110+
#### `label[].strategy = generate` {#label.strategy-generate data-toc-label="generate"}
98111

99-
- `conditional` (default, if `type` key is omitted), where you provide the `name` of the label, and a `script` that returns a boolean for wether the label should be added to the Merge Request.
112+
Use the [`#!yaml generate`](#label.strategy) strategy if you want to create dynamic labels, for example, depending labels based on the file structure within your project.
100113

101-
The `script` must return a `boolean` value, where `true` mean `add the label` and `false` mean `remove the label`.
114+
Thanks to the dynamic nature of the `#!yaml generate` strategy, it has fantastic flexibility, at the cost of greater complexity.
102115

103-
- `generate`, where your `script` generates the list of labels that should be added to the Merge Request.
116+
!!! example "Please see the [*generate labels from directory layout*](examples.md#generate-labels-via-script) example for how to use this"
104117

105-
The `script` must return a `list of strings`, where each label returned will be added to the Merge Request.
118+
### `label[].name` {#label.name data-toc-label="name"}
106119

107-
#### `label[].strategy = conditional` {#label.strategy-conditional data-toc-label="conditional"}
120+
- When using `#!yaml label.strategy: conditional`
108121

109-
Use the `conditional` strategy when you want to add/remove a label on a Merge Request depending on *something*. It's the default strategy, and the most simple one to use.
122+
**REQUIRED** The `#!css name` of the label to create.
110123

111-
!!! note
124+
- When using `#!yaml label.strategy: generate`
112125

113-
The `script` field is a [expr-lang](https://expr-lang.org/) expression, a safe, fast, and intuitive expression evaluator.
114-
115-
```yaml
116-
label:
117-
# Add a "lang/go" label if any "*.go" files was changed
118-
- name: lang/go
119-
color: "$indigo"
120-
script: merge_request.modified_files("*.go")
121-
122-
# Add a "lang/markdown" label if any "*.md" files was changed
123-
- name: lang/markdown
124-
color: "$indigo"
125-
script: merge_request.modified_files("*.md")
126-
127-
# Add a "type/documentation" label if any files was changed within the "docs/" folder
128-
- name: type/documentation
129-
color: "$green"
130-
script: merge_request.modified_files("docs/")
131-
132-
# Add a "go::tests" scoped & prioritized label with value "missing" if no "*_test.go" files was changed
133-
- name: go::tests::missing
134-
color: "$red"
135-
priority: 999
136-
script: not merge_request.modified_files("*_test.go")
137-
138-
# Add a "go::tests" scoped & prioritized label with value "OK" if any "*_test.go" files was changed
139-
- name: go::tests::ok
140-
color: "$green"
141-
priority: 999
142-
script: merge_request.modified_files("*_test.go")
143-
```
126+
**OMITTED** The `#!css name` field must not be set when using the `#!yaml generate` strategy.
144127

145-
#### `label[].strategy = generate` {#label.strategy-generate data-toc-label="generate"}
128+
### `label[].script` {#label.script data-toc-label="script"}
129+
130+
--8<-- "docs/_partials/expr-lang-info.md"
146131

147-
Use the `generate` strategy if you want to manage dynamic labels, for example, depending on the file structure within your project.
148-
149-
> The `script` field is a [expr-lang](https://expr-lang.org/) expression, a safe, fast, and intuitive expression evaluator.
150-
151-
Thanks to the dynamic nature of the `generate` strategy, it has fantastic flexibility, at the cost of greater flexibility.
152-
153-
```yaml
154-
label:
155-
# Generate list of labels via script.
156-
#
157-
# Image you have a project where you have multiple "service" directories
158-
#
159-
# * pkg/service/example/file.go
160-
# * pkg/service/scm/gitlab/file.go
161-
# * pkg/service/scm/github/file.go
162-
#
163-
# and you want to generate a labels like this
164-
#
165-
# * service/example
166-
# * service/scm/gitlab
167-
# * service/scm/github
168-
#
169-
# depending on what directories are having files changed in a Merge Request.
170-
- strategy: generate
171-
description: "Modified this service directory"
172-
color: "$pink"
173-
script: >
174-
// Generate a list of all file paths that was changed in the Merge Request inside pkg/service/
175-
merge_request.modified_files_list("pkg/service/")
176-
177-
// Remove the filename from the path "pkg/service/example/file.go" => "pkg/service/example"
178-
| map({ filepath_dir(#) })
179-
180-
// Remove the prefix "pkg/" from the path "pkg/service/example" => "service/example"
181-
| map({ trimPrefix(#, "pkg/") })
182-
183-
// Remove duplicate values from the output
184-
| uniq()
185-
```
132+
Depending on the `#!yaml label.strategy:` used, the behavior of the script changes, read more about this below.
186133

187134
### `label[].color` {#label.color data-toc-label="color"}
188135

189136
!!! note
190137

191-
When used on `strategy: generate` labels, all generated labels will have the same color.
138+
When used on `#!yaml strategy: generate` labels, all generated labels will have the same color.
192139

193-
`color` is a mandatory field, controlling the background color of the label when viewed in the User Interface.
140+
`#!css color` is a mandatory field, controlling the background color of the label when viewed in the User Interface.
194141

195-
You can either provide your own `#hex` value or use the [Twitter Bootstrap color variables](https://getbootstrap.com/docs/5.3/customize/color/#all-colors), for example `$blue-500` and `$teal`.
142+
You can either provide your own `#!yaml hex` value (e.g, `#FFFF00`) or use the [Twitter Bootstrap color variables](https://getbootstrap.com/docs/5.3/customize/color/#all-colors), for example`#!yaml $blue-500` and `#!yaml $teal`.
196143

197144
### `label[].description` {#label.description data-toc-label="description"}
198145

199-
!!! note
146+
!!! info "When used on [`#!yaml strategy: generate`](#label.strategy-generate) labels, all generated labels will have the same description."
200147

201-
When used on `strategy: generate` labels, all generated labels will have the same description.
202-
203-
An optional key that control the `description` field for the label within GitLab.
148+
An *optional* key that sets the description field for the label within GitLab.
204149

205150
Descriptions are shown in the User Interface when you hover any label.
206151

207152
### `label[].priority` {#label.priority data-toc-label="priority"}
208153

209-
!!! note
210-
211-
When used on `strategy: generate` labels, all generated labels will have the same priority.
154+
!!! info "When used on [`#!yaml strategy: generate`](#label.strategy-generate) labels, all generated labels will have the same priority."
212155

213-
An optional key that controls the [label `priority`](https://docs.gitlab.com/ee/user/project/labels.html#set-label-priority).
156+
An *optional* key that controls the [GitLab Label Priority](https://docs.gitlab.com/ee/user/project/labels.html#set-label-priority){target="_blank"}.
214157

215158
### `label[].skip_if` {#label.skip_if data-toc-label="skip_if"}
216159

217-
An optional key controlling if the label should be skipped (meaning no removal or adding of labels).
160+
--8<-- "docs/_partials/expr-lang-info.md"
161+
162+
!!! tip "The script must return a `boolean` value"
218163

219-
The `skip_if` field must be a valid [Expr-lang](https://expr-lang.org/) expression returning a boolean, where `true` means `skip` and `false` means `process`.
164+
An optional key controlling if the label should be skipped (meaning no removal or adding of labels).

0 commit comments

Comments
 (0)