|
1 | | -# Contributing to Cloudflare's documentation |
| 1 | +# Contributing to Cloudflare's developer documentation |
2 | 2 |
|
3 | | -Before contributing code to Cloudflare's documentation, please read the following guidelines carefully. |
| 3 | +Everyone, including those who are not part of the Cloudflare organization, are encouraged to contribute. |
| 4 | +- If you are not a Cloudflare employee, learn how to contribute in the [contribution page](https://developers.cloudflare.com/style-guide/contributions/) of the Cloudflare Style Guide. |
| 5 | +- If you are a Cloudflare employee, reach out via our Developer Docs space in Google chat. |
4 | 6 |
|
5 | | -## Have feedback for our documentation? Open an issue |
| 7 | +Consult the [Cloudflare Style Guide](https://developers.cloudflare.com/style-guide/) on everything from grammar, to formatting, to frontmatter requirements. Browse our [components](/style-guide/components/) to add additional formatting such as [notes](/style-guide/documentation-content-strategy/component-attributes/notes-tips-warnings/) and [code blocks](/style-guide/components/code/). |
6 | 8 |
|
7 | | -[Open an issue](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) when something in our documentation is incorrect, out-of-date, or if the documentation doesn’t match the actual functionality. |
8 | | - |
9 | | -## Before submitting a PR, open an issue |
10 | | - |
11 | | -Before proposing significant changes, such as adding a new page, [open an issue](https://github.com/cloudflare/cloudflare-docs/issues/new/choose) so that we can discuss your approach first. Only members of the Cloudflare organization can open a pull request on the repository, and they should follow the same guidance on opening an issue for significant changes. If you’re not part of the Cloudflare organization but want to contribute, fork the repository and then create a pull request. |
12 | | - |
13 | | -A member of the Product Content Experience team will review the pull request. If the changes are straightforward, the pull request is approved and can be merged. If the pull request is more technical and requires an additional review, the new reviewer will leave any additional feedback. |
14 | | - |
15 | | -If a pull request is not approved, the “won't fix” label is applied and a comment is added to explain why the pull request was closed. |
16 | | - |
17 | | -If we require more information to address your pull request, the `more-information-needed` label will be applied to the pull request. If more information has not been provided within fourteen days, the pull request will automatically close. |
18 | | - |
19 | | -### Pull Request Guidelines |
20 | | - |
21 | | -- Commits and commit messages |
22 | | - - Use smaller commits for your work to make it easier to review. In your commit messages, be specific about what you changed in the files. |
23 | | - - If you are proposing a new page, review our [content type guidelines](https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/) for options and templates. |
24 | | -- Pull request titles |
25 | | - - Follow the title structure of [Product Name] + work you did + affected file(s) |
26 | | - - Example: [Access] fix broken link in example_file.md |
27 | | -- Pull request descriptions |
28 | | - - Use bullet points to summarize the changes in the commits |
29 | | - - Add any other information you think is helpful or needs to be addressed. If your PR fixes an open issue, indicate that your PR is addressing the issue and provide a link to the issue. |
30 | | - |
31 | | -## Package manager |
32 | | - |
33 | | -- [npm](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager#introduction-to-npm) is the recommended package manager that must be used in installing dependencies. |
34 | | -- The generated `package-lock.json` file must be committed to git. |
35 | | - |
36 | | -## Wrangler config |
37 | | - |
38 | | -If you are adding a code snippet to the docs that represents a Wrangler config file (`wrangler.toml`, `wrangler.json`, or `wrangler.jsonc`) make sure you wrap it with the `<WranglerConfig>` component, which ensures it is rendered as both JSON and TOML. For example: |
39 | | - |
40 | | -```` |
41 | | -
|
42 | | -import { WranglerConfig } from "~/components"; |
43 | | -
|
44 | | -<WranglerConfig> |
45 | | -
|
46 | | -```toml |
47 | | -# Top-level configuration |
48 | | -name = "my-worker" |
49 | | -main = "src/index.js" |
50 | | -compatibility_date = "2022-07-12" |
51 | | -
|
52 | | -workers_dev = false |
53 | | -route = { pattern = "example.org/*", zone_name = "example.org" } |
54 | | -
|
55 | | -kv_namespaces = [ |
56 | | - { binding = "<MY_NAMESPACE>", id = "<KV_ID>" } |
57 | | -] |
58 | | -
|
59 | | -[env.staging] |
60 | | -name = "my-worker-staging" |
61 | | -route = { pattern = "staging.example.org/*", zone_name = "example.org" } |
62 | | -
|
63 | | -kv_namespaces = [ |
64 | | - { binding = "<MY_NAMESPACE>", id = "<STAGING_KV_ID>" } |
65 | | -] |
66 | | -``` |
67 | | -
|
68 | | -</WranglerConfig> |
69 | | -
|
70 | | -```` |
71 | | - |
72 | | -## Workers Playground |
73 | | - |
74 | | -If you are adding a code snippet to the docs that is: |
75 | | - |
76 | | -1. A fully contained, valid Worker (i.e. it does not require external dependencies or specific bindings) |
77 | | -2. Only JavaScript |
78 | | - |
79 | | -you can add `playground: true` to the code block metadata to render a button to let users open the Worker in the [Playground](https://workers.new). For example: |
80 | | - |
81 | | -```` |
82 | | -```js |
83 | | ---- |
84 | | -playground: true |
85 | | ---- |
86 | | -export default { |
87 | | - async fetch(request) { |
88 | | - /** |
89 | | - * Replace `remote` with the host you wish to send requests to |
90 | | - */ |
91 | | - const remote = "https://example.com"; |
92 | | -
|
93 | | - return await fetch(remote, request); |
94 | | - }, |
95 | | -}; |
96 | | -``` |
97 | | -```` |
98 | | - |
99 | | -would render as |
100 | | - |
101 | | -<img width="870" alt="Screenshot 2024-02-20 at 14 29 22" src="https://github.com/cloudflare/cloudflare-docs/assets/28503158/56aa8016-b3b6-4d64-8213-b1a26f16534a"> |
102 | | - |
103 | | -## GraphQL API Explorer |
104 | | - |
105 | | -If you are adding a code snippet to the documentation that is an executable GraphQL query, you can add `graphql-api-explorer` right after `graphql` in the code block metadata (both must be present). This will render a button that allows users to open the query in the [GraphQL API Explorer](https://graphql.cloudflare.com/explorer). For example: |
106 | | - |
107 | | -```` |
108 | | -```graphql graphql-api-explorer title="A GraphQL query" |
109 | | -query GraphqlExample($zoneTag: string, $start: Time, $end: Time) { |
110 | | - viewer { |
111 | | - zones(filter: { zoneTag: $zoneTag }) { |
112 | | - firewallEventsAdaptive( |
113 | | - filter: { datetime_gt: $start, datetime_lt: $end } |
114 | | - limit: 2 |
115 | | - orderBy: [datetime_DESC] |
116 | | - ) { |
117 | | - action |
118 | | - datetime |
119 | | - host: clientRequestHTTPHost |
120 | | - } |
121 | | - } |
122 | | - } |
123 | | -} |
124 | | -``` |
125 | | -```` |
126 | | - |
127 | | -When a user selects the `Run in GraphQL API Explorer` button, the following variables will be pre-populated in the GraphQL API Explorer along with the query. |
128 | | - |
129 | | -:::note |
130 | | -The user must be logged in or have an API token saved to see the query and variables pre-populated. |
131 | | -::: |
132 | | - |
133 | | -``` |
134 | | -{"zoneTag":"ZONE_ID", "start":"2025-05-07T14:54:36Z", "end":"2025-05-07T20:54:36Z"} |
135 | | -``` |
136 | | - |
137 | | -### Conventions to auto populate `Variables` section in the GraphQL API Explorer |
138 | | - |
139 | | -By default, the `Variables` section will be automatically populated based on the variables used in the GraphQL query. |
140 | | - |
141 | | -- Any variable name that includes `start` and has a type of `Time` --> start: "2025-05-09T14:58:06Z" (6 hours from the current time) |
142 | | - - e.g. `datetimeStart` also has `start` keyword, so it will be recognized for a start time (or date) |
143 | | -- Any variable name that includes `end` and has a type of `Time` --> end: "2025-05-09T20:58:06Z" (current time) |
144 | | -- Any variable name that includes `start` and has a type of `Date` --> start: "2025-05-07" (24 hours from the current date) |
145 | | -- Any variable name that includes `end` and has a type of `Date` --> end: "2025-05-08" (current date) |
146 | | -- `zoneTag` and has a type of `string` --> zoneTag: "ZONE_ID" |
147 | | -- `accountTag` and has a type of `string` --> accountTag: "ACCOUNT_ID" |
148 | | -- Any variable name that includes `id` and has a type of `string` --> id: "REPLACE_WITH_ID" |
149 | | -- Any variable name and has a type of string --> anyString: "REPLACE_WITH_STRING" |
150 | | -- `limit` with type `*int*` --> limit: 100 |
151 | | - |
152 | | -In addition to the variables that are automatically populated, you can add custom variables by setting their values as a JSON string in the `graphql-api-explorer` metadata. |
153 | | - |
154 | | -```` |
155 | | -```graphql graphql-api-explorer='{"uID": "something"}' title="A GraphQL query" |
156 | | -query GraphqlExample($zoneTag: string, $start: Time, $end: Time) { |
157 | | - viewer { |
158 | | - zones(filter: { zoneTag: $zoneTag }) { |
159 | | - ... |
160 | | - } |
161 | | - } |
162 | | -} |
163 | | -```` |
164 | | - |
165 | | -The variables added via the metadata value will be merged with the automatically populated variables. |
166 | | - |
167 | | -``` |
168 | | -{"zoneTag":"ZONE_ID", "start":"2025-05-07T14:54:36Z", "end":"2025-05-07T20:54:36Z", "uId": "something"} |
169 | | -``` |
| 9 | +Thank you for helping us to maintain quality documentation. |
0 commit comments