1
1
---
2
- sidebarDepth : 2
3
- search : false
2
+ search :
3
+ exclude : true
4
4
---
5
5
6
6
# Contributing
@@ -12,89 +12,86 @@ please [open an issue](https://github.com/uber-go/fx/issues/new)
12
12
describing your proposal.
13
13
Discussing API changes ahead of time makes pull request review much smoother.
14
14
15
- ::: tip
16
- You'll need to sign [ Uber's CLA] ( https://cla-assistant.io/uber-go/fx )
17
- before we can accept any of your contributions.
18
- If necessary, a bot will remind
19
- you to accept the CLA when you open your pull request.
20
- :::
15
+ !!! tip
16
+
17
+ You'll need to sign [Uber's CLA](https://cla-assistant.io/uber-go/fx)
18
+ before we can accept any of your contributions.
19
+ If necessary, a bot will remind
20
+ you to accept the CLA when you open your pull request.
21
+
21
22
22
23
## Contribute code
23
24
24
25
Set up your local development environment to contribute to Fx.
25
26
26
27
1 . [ Fork] ( https://github.com/uber-go/fx/fork ) , then clone the repository.
27
28
28
- <code-group >
29
- <code-block title =" Git " >
30
- ``` bash
31
- git clone https://github.com/your_github_username/fx.git
32
- cd fx
33
- git remote add upstream https://github.com/uber-go/fx.git
34
- git fetch upstream
35
- ```
36
- </code-block >
37
-
38
- <code-block title =" GitHub CLI " >
39
- ``` bash
40
- gh repo fork --clone uber-go/fx
41
- ```
42
- </code-block >
43
- </code-group >
29
+ === "Git"
30
+
31
+ ```bash
32
+ git clone https://github.com/your_github_username/fx.git
33
+ cd fx
34
+ git remote add upstream https://github.com/uber-go/fx.git
35
+ git fetch upstream
36
+ ```
37
+
38
+ === "GitHub CLI"
39
+
40
+ ```bash
41
+ gh repo fork --clone uber-go/fx
42
+ ```
44
43
45
44
2 . Install Fx's dependencies:
46
45
47
- ``` bash
48
- go mod download
49
- ```
46
+ ``` bash
47
+ go mod download
48
+ ```
50
49
51
50
3. Verify that tests and other checks pass locally.
52
51
53
- ``` bash
54
- make lint
55
- make test
56
- ```
52
+ ` ` ` bash
53
+ make lint
54
+ make test
55
+ ` ` `
57
56
58
- Note that for ` make lint ` to work,
59
- you must be using the latest stable version of Go.
60
- If you're on an older version, you can still contribute your change,
61
- but we may discover style violations when you open the pull request.
57
+ Note that for ` make lint` to work,
58
+ you must be using the latest stable version of Go.
59
+ If you' re on an older version, you can still contribute your change,
60
+ but we may discover style violations when you open the pull request.
62
61
63
62
Next, make your changes.
64
63
65
64
1. Create a new feature branch.
66
65
67
- ``` bash
68
- git checkout master
69
- git pull
70
- git checkout -b cool_new_feature
71
- ```
66
+ ```bash
67
+ git checkout master
68
+ git pull
69
+ git checkout -b cool_new_feature
70
+ ```
72
71
73
72
2. Make your changes, and verify that all tests and lints still pass.
74
73
75
- ``` bash
76
- $EDITOR app.go
77
- make lint
78
- make test
79
- ```
74
+ ```bash
75
+ $EDITOR app.go
76
+ make lint
77
+ make test
78
+ ```
80
79
81
80
3. When you' re satisfied with the change,
82
81
push it to your fork and make a pull request.
83
82
84
- <code-group >
85
- <code-block title =" Git " >
86
- ``` bash
87
- git push origin cool_new_feature
88
- # Open a PR at https://github.com/uber-go/fx/compare
89
- ```
90
- </code-block >
91
-
92
- <code-block title =" GitHub CLI " >
93
- ``` bash
94
- gh pr create
95
- ```
96
- </code-block >
97
- </code-group >
83
+ === " Git"
84
+
85
+ ` ` ` bash
86
+ git push origin cool_new_feature
87
+ # Open a PR at https://github.com/uber-go/fx/compare
88
+ ` ` `
89
+
90
+ === " GitHub CLI"
91
+
92
+ ` ` ` bash
93
+ gh pr create
94
+ ` ` `
98
95
99
96
At this point, you' re waiting on us to review your changes.
100
97
We *try* to respond to issues and pull requests within a few business days,
@@ -115,18 +112,14 @@ To contribute documentation to Fx,
115
112
1. Set up your local development environment
116
113
as you would to [contribute code](#contribute-code).
117
114
118
- 2 . Install the documentation website dependencies.
119
-
120
- ``` bash
121
- cd docs
122
- yarn install
123
- ```
115
+ 2. [Install uv](https://docs.astral.sh/uv/getting-started/installation/).
116
+ We use this to manage our Python dependencies.
124
117
125
118
3. Run the development server.
126
119
127
- ``` bash
128
- yarn dev
129
- ```
120
+ ```bash
121
+ make serve
122
+ ```
130
123
131
124
4. Make your changes.
132
125
@@ -208,84 +201,54 @@ Markdown will reflow this into a "normal" pargraph when rendering.
208
201
209
202
All code samples in documentation must be buildable and testable.
210
203
211
- To aid in this, we have two tools:
204
+ To make this possible, we put code samples in the " ex/" directory,
205
+ and use the [PyMdown Snippets extension](https://facelessuser.github.io/pymdown-extensions/extensions/snippets/)
206
+ to include them in the documentation.
212
207
213
- - [ mdox ] ( https://github.com/bwplotka/mdox/ )
214
- - the ` region ` shell script
208
+ To include code snippets in your documentation,
209
+ take the following steps:
215
210
216
- #### mdox
211
+ 1. Add source code under the ` ex/` directory.
212
+ Usually, the file will be placed in a directory
213
+ with a name matching the documentation file
214
+ that will include the snippet.
217
215
218
- mdox is a Markdown file formatter that includes support for
219
- running a command and using its output as part of a code block.
220
- To use this, declare a regular code block and tag it with ` mdoc-exec ` .
216
+ For example,
217
+ for src/annotation.md, examples will reside in ex/annotation/.
221
218
222
- ``` markdown
223
- ```go mdox-exec='cat foo.go'
224
- // ...
225
- ```
219
+ 2. Inside the source file, name regions of code with comments in the forms:
226
220
227
- The contents of the code block will be replaced
228
- with the output of the command when you run ` make fmt `
229
- in the docs directory.
230
- ` make check ` will ensure that the contents are up-to-date.
221
+ ` ` `
222
+ // --8< -- [start:name]
223
+ ...
224
+ // --8< -- [end:name]
225
+ ` ` `
231
226
232
- The command runs with the working directory set to docs/ .
233
- Store code samples in ex/ and reference them directly.
227
+ Where ` name ` is the name of the snippet .
228
+ For example:
234
229
235
- #### region
230
+ ` ` ` go
231
+ // --8< -- [start:New]
232
+ func New () * http.Server {
233
+ // ...
234
+ }
235
+ // --8< -- [end:New]
236
+ ` ` `
236
237
237
- The ` region ` shell script is a command intended to be used with ` mdox-exec ` .
238
+ 3. Include the snippet in a code block with the following syntax:
238
239
239
- ``` plain mdox-exec='region' mdox-expect-exit-code='1'
240
- USAGE: region FILE REGION1 REGION2 ...
240
+ ` ` ` markdown
241
+ ` ` ` go
242
+ ;--8<-- " path/to/file.go:name"
243
+ ` ` `
241
244
242
- Extracts text from FILE marked by "// region" blocks.
243
- ```
245
+ Where ` path/to/file.go` is the path to the file containing the snippet
246
+ relative to the ` ex/` directory,
247
+ and ` name` is the name of the snippet.
244
248
245
- For example, given the file:
249
+ You can include multiple snippets from the same file like so :
246
250
247
- ```
248
- foo
249
- // region myregion
250
- bar
251
- // endregion myregion
252
- baz
253
- ```
254
-
255
- Running ` region $FILE myregion ` will print:
256
-
257
- ```
258
- bar
259
- ```
260
-
261
- The same region name may be used multiple times
262
- to pull different snippets from the same file.
263
- For example, given the file:
264
-
265
- ``` go
266
- // region provide-foo
267
- func main () {
268
- fx.New (
269
- fx.Provide (
270
- NewFoo,
271
- // endregion provide-foo
272
- NewBar,
273
- // region provide-foo
274
- ),
275
- ).Run ()
276
- }
277
-
278
- // endregion provide-foo
279
- ```
280
-
281
- ` region $FILE provide-foo ` will print,
282
-
283
- ``` go
284
- func main () {
285
- fx.New (
286
- fx.Provide (
287
- NewFoo,
288
- ),
289
- ).Run ()
290
- }
291
- ```
251
+ ` ` `
252
+ ;--8<-- " path/to/file.go:snippet1"
253
+ ;--8<-- " path/to/file.go:snippet2"
254
+ ` ` `
0 commit comments