|
3 | 3 | **Thanks for your interest in contributing to |
4 | 4 | [OpenTelemetry.io](https://opentelemetry.io/)!** |
5 | 5 |
|
6 | | -Follow these guidelines helps to communicate that you respect the time of the |
7 | | -contributors managing and developing this open source project. In return, |
8 | | -maintainers and approvers should reciprocate that respect in addressing your |
9 | | -issue, assessing changes, and helping you finalize your pull requests. In that |
10 | | -spirit of mutual respect, we endeavor to review incoming issues and pull |
11 | | -requests, and will close any lingering issues or pull requests after long times |
12 | | -of inactivity. |
13 | | - |
14 | | -## Before you get started |
15 | | - |
16 | | -### Code of Conduct |
17 | | - |
18 | | -All of your interactions in this project are subject to our |
19 | | -[Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md). |
20 | | -This includes the creation of issues or pull requests, commenting on issues or |
21 | | -pull requests, and extends to all interactions in any real-time space, for |
22 | | -example Slack, Discord, and so on. |
23 | | - |
24 | | -### Contributor License Agreement |
25 | | - |
26 | | -Review the general |
27 | | -[OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md), |
28 | | -as it provides additional details, especially that you need to sign a |
29 | | -Contributor License Agreement (CLA) before you can contribute. |
30 | | - |
31 | | -### Found a security issue? |
32 | | - |
33 | | -If you discover a security issue, read the |
34 | | -[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy) |
35 | | -before opening an issue. |
36 | | - |
37 | | -### Found a problem? |
38 | | - |
39 | | -If you find a bug or a problem with the content of this repository, or you would |
40 | | -like to request an enhancement, [create an issue][new-issue]. |
41 | | - |
42 | | -Before reporting a new issue, make sure that the issue was not already reported |
43 | | -or fixed by searching through our |
44 | | -[issues list](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc). |
45 | | - |
46 | | -When creating a new issue, include a short, meaningful title and a clear |
47 | | -description. Add as much relevant information as you can, and, if possible, a |
48 | | -test case. |
49 | | - |
50 | | -### Want to work on an existing issue? |
51 | | - |
52 | | -This is the best way how you can help us to make our documentation better! Take |
53 | | -a look at issues tagged with |
54 | | -[help wanted](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22) |
55 | | -and |
56 | | -[good first issue](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22) |
57 | | -to find an opportunity to contribute and help us. The good first issue label |
58 | | -indicates that members have committed to providing extra assistance for new |
59 | | -contributors. |
60 | | - |
61 | | -After picking an issue, read through the existing discussion, ask the |
62 | | -maintainers if this issue is still relevant and ask all questions you need for |
63 | | -clarification. Afterwards you can state in a comment that you intend to work on |
64 | | -this issue and it will be assumed to be yours. We will **not** assign issues to |
65 | | -non-community members who have already made contributions to the [OpenTelemetry |
66 | | -organization][org]. After confirmation through a maintainer, plan to provide a |
67 | | -PR shortly or let maintainers now if you run into any blockers. |
68 | | - |
69 | | -## Contributor's guide |
70 | | - |
71 | | -To learn how to contribute fixes and new content to this project, read the |
72 | | -[Contributor's guide](https://opentelemetry.io/docs/contributing/), which |
73 | | -includes a style guide and useful information on the review process. |
74 | | - |
75 | | -## Development |
76 | | - |
77 | | -The following instructions will help you to setup a development environment of |
78 | | -the <https://opentelemetry.io/> website. |
79 | | - |
80 | | -### Setup |
81 | | - |
82 | | -#### Cloud-IDE setup |
83 | | - |
84 | | -These instructions are for [Gitpod.io][], adjust as needed for your favorite |
85 | | -cloud IDE: |
86 | | - |
87 | | -1. Fork this repository. For help, see [Fork a repository][fork]. |
88 | | -2. From [gitpod.io/workspaces][], create a new workspace (do this only once) or |
89 | | - open an existing workspace over your fork. You can also visit a link of the |
90 | | - form: |
91 | | - <https://gitpod.io#https://github.com/YOUR_GITHUB_ID/opentelemetry.io>. |
92 | | - |
93 | | - > **Note**: If you have the necessary permissions to work from this |
94 | | - > repository, or just want to look around, open |
95 | | - > <https://gitpod.io/#https://github.com/open-telemetry/opentelemetry.io>. |
96 | | -
|
97 | | -Gitpod will automatically install the repo-specific packages for you. You're now |
98 | | -ready to [build](#build), [serve](#serve) and/or make updates to the website |
99 | | -files. |
100 | | - |
101 | | -#### Local setup |
102 | | - |
103 | | -1. [Fork][] and then [clone][] this repository. |
104 | | -2. **Change** to the repository directory. |
105 | | -3. **Install or upgrade** to the [**active LTS** release][nodejs-rel] of |
106 | | - **Node.js**. We recommend using **[nvm][]** to manage your Node |
107 | | - installation. Under Linux, run the following command (which will |
108 | | - install/upgrade to the version specified in [.nvmrc][]): |
109 | | - |
110 | | - ```sh |
111 | | - nvm install |
112 | | - ``` |
113 | | - |
114 | | - To [install under Windows][nodejs-win], use [nvm-windows][]: |
115 | | - |
116 | | - ```cmd |
117 | | - > nvm install lts && nvm use lts |
118 | | - ``` |
119 | | - |
120 | | -4. Get npm packages and other prerequisites: |
121 | | - |
122 | | - ```sh |
123 | | - npm install |
124 | | - ``` |
125 | | - |
126 | | -You're now ready to [build](#build), [serve](#serve) and/or make updates to the |
127 | | -website files. |
128 | | -
|
129 | | -### Build |
130 | | -
|
131 | | -To **build** the site run: |
132 | | -
|
133 | | -```sh |
134 | | -npm run build |
135 | | -``` |
136 | | -
|
137 | | -You'll find the generated site files under `public`. |
138 | | - |
139 | | -### Serve |
140 | | - |
141 | | -To **serve** the site run: |
142 | | - |
143 | | -```sh |
144 | | -npm run serve |
145 | | -``` |
146 | | - |
147 | | -The site will be served at [localhost:1313][]. |
148 | | - |
149 | | -If you need to test [Netlify] redirects, use the following command, and visit |
150 | | -the site at [localhost:8888][]: |
151 | | - |
152 | | -```sh |
153 | | -npm run serve:netlify |
154 | | -``` |
155 | | - |
156 | | -> **Note 1**: The serve command serves files from memory, not from disk. |
157 | | -> |
158 | | -> **Note 2**: See an error like `too many open files` or `pipe failed` under |
159 | | -> macOS? You may need to increase the file descriptor limit. See |
160 | | -> [Hugo issue #6109](https://github.com/gohugoio/hugo/issues/6109). |
161 | | - |
162 | | -### Content and submodules |
163 | | - |
164 | | -The website is built from the following content: |
165 | | - |
166 | | -- Files under `content/`, `static/`, etc. per [Hugo][] defaults. |
167 | | -- Mount points, defined in [hugo.yaml][] under `mounts`. Mounts are either |
168 | | - directly from git submodules under [content-modules][], or preprocessed |
169 | | - content from `content-modules` (placed under `tmp/`), and no where else. |
170 | | - |
171 | | -[hugo.yaml]: |
172 | | - https://github.com/open-telemetry/opentelemetry.io/blob/main/hugo.yaml |
173 | | -[content-modules]: |
174 | | - https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules |
175 | | - |
176 | | -### Submodule changes |
177 | | - |
178 | | -If you change any content inside of a [content-modules][] submodule, then you'll |
179 | | -need to **_first_** submit a PR (containing the submodule changes) to the |
180 | | -submodule's repository. Only after the submodule PR has been accepted, can you |
181 | | -update the submodule and have the changes appear in this website. |
182 | | - |
183 | | -It is easiest to manage your `content-modules` changes by working with the |
184 | | -repository that the corresponding submodule is linked to, rather than inside the |
185 | | -submodule itself. |
186 | | - |
187 | | -> **For expert contributors**, you can work directly in the submodule. You'll |
188 | | -> then be able to directly build and serve your (submodule) changes. By default, |
189 | | -> the CI scripts get submodules on every invocation. To prevent this behavior |
190 | | -> while you work within a submodule, set the environment variable `GET=no`. |
191 | | -> You'll also need to `git fetch --unshallow` the submodule before you can |
192 | | -> submit a PR. Alternatively, set `DEPTH=100` and re-fetch submodules. |
193 | | - |
194 | | -## Approver and Maintainer practices |
195 | | - |
196 | | -This last section includes guidelines and some common practices used by |
197 | | -approvers and maintainers while doing code reviews: |
198 | | - |
199 | | -- PRs with changes to documentation co-owned by a SIG (collector, demo, |
200 | | - language-specific...) should aim for two approvals: one by a docs approver and |
201 | | - one by a SIG approver: |
202 | | - - Doc approver label such PRs with `sig:<name>` and tag the SIG `-approvers` |
203 | | - group on that PR |
204 | | - - If no SIG approval is given within a certain grace period (two weeks in |
205 | | - general, but may be less in urgent cases), docs maintainer may use their own |
206 | | - judgement to merge that PR |
207 | | -- If the PR branch is `out-of-date with the base branch`, they do not need to be |
208 | | - updated continuously: every update triggers all the PR CI checks to be run! |
209 | | - It's often enough to update them before merging. |
210 | | -- A PR by non-maintainers should **never** update git sub modules. This happens |
211 | | - by accident from time to time. Let the PR author know that they should not |
212 | | - worry about it, we will fix this before merging, but in the future they should |
213 | | - make sure that they work from an up-to-date fork. |
214 | | -- If the contributor is having trouble signing the CLA or used the wrong email |
215 | | - by mistake in one of their commits, ask them to fix the issue or rebase the |
216 | | - pull request. Worst case scenario, close and re-open the PR to trigger a new |
217 | | - CLA check. |
218 | | -- Words unknown to cspell should be added to the cspell ignore list per page by |
219 | | - PR authors. Only approvers and maintainers will add commonly used terms to the |
220 | | - global list. |
221 | | -- When an approver or maintainer won't be available to contribute for an |
222 | | - extended period of time (more than a few days or a week) or won't be available |
223 | | - in that period of time, they should communicate this using the |
224 | | - [#otel-comms](https://cloud-native.slack.com/archives/C02UN96HZH6) channel and |
225 | | - updating the GitHub status. |
226 | | -
|
227 | | -[.nvmrc]: .nvmrc |
228 | | -[clone]: |
229 | | - https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository |
230 | | -[fork]: https://docs.github.com/en/get-started/quickstart/fork-a-repo |
231 | | -[gitpod.io]: https://gitpod.io |
232 | | -[gitpod.io/workspaces]: https://gitpod.io/workspaces |
233 | | -[hugo]: https://gohugo.io |
234 | | -[localhost:1313]: http://localhost:1313 |
235 | | -[localhost:8888]: http://localhost:8888 |
236 | | -[netlify]: https://netlify.com |
237 | | -[new-issue]: |
238 | | - https://github.com/open-telemetry/opentelemetry.io/issues/new/choose |
239 | | -[nodejs-rel]: https://nodejs.org/en/about/previous-releases |
240 | | -[nodejs-win]: |
241 | | - https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows |
242 | | -[nvm]: |
243 | | - https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating |
244 | | -[nvm-windows]: https://github.com/coreybutler/nvm-windows |
245 | | -[org]: https://github.com/open-telemetry |
| 6 | +To learn how to contribute new content and fixes to this project, see |
| 7 | +[Contributing](https://opentelemetry.io/docs/contributing/), which includes a |
| 8 | +style guide and useful information on the review process. |
0 commit comments