Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Further consolidate Contributing guides #4654

Merged
merged 21 commits into from
Jun 13, 2024
Merged

Further consolidate Contributing guides #4654

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
7b51ca4
Rearrange guide
theletterf Jun 11, 2024
fdf17ab
Further edits
theletterf Jun 11, 2024
69828ed
Fix spelling
theletterf Jun 11, 2024
c8592b3
Fix format and links
theletterf Jun 11, 2024
b78adfc
Add description
theletterf Jun 11, 2024
a017abb
Another description and title
theletterf Jun 11, 2024
ee6c949
Update CONTRIBUTING.md
theletterf Jun 12, 2024
570db1d
Merge branch 'main' into theletterf-consolidate-contributing-guides-f…
theletterf Jun 12, 2024
3c841cf
Some edits
theletterf Jun 12, 2024
e4462ef
Fix links
theletterf Jun 12, 2024
76aab14
Further fix the README
theletterf Jun 12, 2024
c281b16
Merge branch 'main' into theletterf-consolidate-contributing-guides-f…
theletterf Jun 12, 2024
e8f1aac
Merge branch 'main' into theletterf-consolidate-contributing-guides-f…
theletterf Jun 13, 2024
2a02db9
Update CONTRIBUTING.md
theletterf Jun 13, 2024
7c04bdb
Update content/en/docs/contributing/pr-checks.md
theletterf Jun 13, 2024
2b8b4bb
Update content/en/docs/contributing/pr-checks.md
theletterf Jun 13, 2024
6993fd3
Merge branch 'main' into theletterf-consolidate-contributing-guides-f…
theletterf Jun 13, 2024
6e16f18
Rearrange docs
theletterf Jun 13, 2024
db24032
Fixes
theletterf Jun 13, 2024
7ffecb3
Merge branch 'main' into theletterf-consolidate-contributing-guides-f…
theletterf Jun 13, 2024
8e5bc3f
Add cSPell exception
theletterf Jun 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
243 changes: 3 additions & 240 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,243 +3,6 @@
**Thanks for your interest in contributing to
[OpenTelemetry.io](https://opentelemetry.io/)!**

Follow these guidelines helps to communicate that you respect the time of the
contributors managing and developing this open source project. In return,
maintainers and approvers should reciprocate that respect in addressing your
issue, assessing changes, and helping you finalize your pull requests. In that
spirit of mutual respect, we endeavor to review incoming issues and pull
requests, and will close any lingering issues or pull requests after long times
of inactivity.

## Before you get started

### Code of Conduct

All of your interactions in this project are subject to our
[Code of Conduct](https://github.com/open-telemetry/community/blob/main/code-of-conduct.md).
This includes the creation of issues or pull requests, commenting on issues or
pull requests, and extends to all interactions in any real-time space, for
example Slack, Discord, and so on.

### Contributor License Agreement

Review the general
[OpenTelemetry Contributor Guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md),
as it provides additional details, especially that you need to sign a
Contributor License Agreement (CLA) before you can contribute.

### Found a security issue?

If you discover a security issue, read the
[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy)
before opening an issue.

### Found a problem?

If you find a bug or a problem with the content of this repository, or you would
like to request an enhancement, [create an issue][new-issue].

Before reporting a new issue, make sure that the issue was not already reported
or fixed by searching through our
[issues list](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc).

When creating a new issue, include a short, meaningful title and a clear
description. Add as much relevant information as you can, and, if possible, a
test case.

### Want to work on an existing issue?

This is the best way how you can help us to make our documentation better! Take
a look at issues tagged with
[help wanted](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22)
and
[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)
to find an opportunity to contribute and help us. The good first issue label
indicates that members have committed to providing extra assistance for new
contributors.

After picking an issue, read through the existing discussion, ask the
maintainers if this issue is still relevant and ask all questions you need for
clarification. Afterwards you can state in a comment that you intend to work on
this issue and it will be assumed to be yours. We will **not** assign issues to
non-community members who have already made contributions to the [OpenTelemetry
organization][org]. After confirmation through a maintainer, plan to provide a
PR shortly or let maintainers now if you run into any blockers.

## Contributor's guide

To learn how to contribute fixes and new content to this project, read the
[Contributor's guide](https://opentelemetry.io/docs/contributing/), which
includes a style guide and useful information on the review process.

## Development

The following instructions will help you to setup a development environment of
the <https://opentelemetry.io/> website.

### Setup

#### Cloud-IDE setup

These instructions are for [Gitpod.io][], adjust as needed for your favorite
cloud IDE:

1. Fork this repository. For help, see [Fork a repository][fork].
2. From [gitpod.io/workspaces][], create a new workspace (do this only once) or
open an existing workspace over your fork. You can also visit a link of the
form:
<https://gitpod.io#https://github.com/YOUR_GITHUB_ID/opentelemetry.io>.

> **Note**: If you have the necessary permissions to work from this
> repository, or just want to look around, open
> <https://gitpod.io/#https://github.com/open-telemetry/opentelemetry.io>.

Gitpod will automatically install the repo-specific packages for you. You're now
ready to [build](#build), [serve](#serve) and/or make updates to the website
files.

#### Local setup

1. [Fork][] and then [clone][] this repository.
2. **Change** to the repository directory.
3. **Install or upgrade** to the [**active LTS** release][nodejs-rel] of
**Node.js**. We recommend using **[nvm][]** to manage your Node
installation. Under Linux, run the following command (which will
install/upgrade to the version specified in [.nvmrc][]):

```sh
nvm install
```

To [install under Windows][nodejs-win], use [nvm-windows][]:

```cmd
> nvm install lts && nvm use lts
```

4. Get npm packages and other prerequisites:

```sh
npm install
```

You're now ready to [build](#build), [serve](#serve) and/or make updates to the
website files.

### Build

To **build** the site run:

```sh
npm run build
```

You'll find the generated site files under `public`.

### Serve

To **serve** the site run:

```sh
npm run serve
```

The site will be served at [localhost:1313][].

If you need to test [Netlify] redirects, use the following command, and visit
the site at [localhost:8888][]:

```sh
npm run serve:netlify
```

> **Note 1**: The serve command serves files from memory, not from disk.
>
> **Note 2**: See an error like `too many open files` or `pipe failed` under
> macOS? You may need to increase the file descriptor limit. See
> [Hugo issue #6109](https://github.com/gohugoio/hugo/issues/6109).

### Content and submodules

The website is built from the following content:

- Files under `content/`, `static/`, etc. per [Hugo][] defaults.
- Mount points, defined in [hugo.yaml][] under `mounts`. Mounts are either
directly from git submodules under [content-modules][], or preprocessed
content from `content-modules` (placed under `tmp/`), and no where else.

[hugo.yaml]:
https://github.com/open-telemetry/opentelemetry.io/blob/main/hugo.yaml
[content-modules]:
https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules

### Submodule changes

If you change any content inside of a [content-modules][] submodule, then you'll
need to **_first_** submit a PR (containing the submodule changes) to the
submodule's repository. Only after the submodule PR has been accepted, can you
update the submodule and have the changes appear in this website.

It is easiest to manage your `content-modules` changes by working with the
repository that the corresponding submodule is linked to, rather than inside the
submodule itself.

> **For expert contributors**, you can work directly in the submodule. You'll
> then be able to directly build and serve your (submodule) changes. By default,
> the CI scripts get submodules on every invocation. To prevent this behavior
> while you work within a submodule, set the environment variable `GET=no`.
> You'll also need to `git fetch --unshallow` the submodule before you can
> submit a PR. Alternatively, set `DEPTH=100` and re-fetch submodules.

## Approver and Maintainer practices

This last section includes guidelines and some common practices used by
approvers and maintainers while doing code reviews:

- PRs with changes to documentation co-owned by a SIG (collector, demo,
language-specific...) should aim for two approvals: one by a docs approver and
one by a SIG approver:
- Doc approver label such PRs with `sig:<name>` and tag the SIG `-approvers`
group on that PR
- If no SIG approval is given within a certain grace period (two weeks in
general, but may be less in urgent cases), docs maintainer may use their own
judgement to merge that PR
- If the PR branch is `out-of-date with the base branch`, they do not need to be
updated continuously: every update triggers all the PR CI checks to be run!
It's often enough to update them before merging.
- A PR by non-maintainers should **never** update git sub modules. This happens
by accident from time to time. Let the PR author know that they should not
worry about it, we will fix this before merging, but in the future they should
make sure that they work from an up-to-date fork.
- If the contributor is having trouble signing the CLA or used the wrong email
by mistake in one of their commits, ask them to fix the issue or rebase the
pull request. Worst case scenario, close and re-open the PR to trigger a new
CLA check.
- Words unknown to cspell should be added to the cspell ignore list per page by
PR authors. Only approvers and maintainers will add commonly used terms to the
global list.
- When an approver or maintainer won't be available to contribute for an
extended period of time (more than a few days or a week) or won't be available
in that period of time, they should communicate this using the
[#otel-comms](https://cloud-native.slack.com/archives/C02UN96HZH6) channel and
updating the GitHub status.

[.nvmrc]: .nvmrc
[clone]:
https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository
[fork]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
[gitpod.io]: https://gitpod.io
[gitpod.io/workspaces]: https://gitpod.io/workspaces
[hugo]: https://gohugo.io
[localhost:1313]: http://localhost:1313
[localhost:8888]: http://localhost:8888
[netlify]: https://netlify.com
[new-issue]:
https://github.com/open-telemetry/opentelemetry.io/issues/new/choose
[nodejs-rel]: https://nodejs.org/en/about/previous-releases
[nodejs-win]:
https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows
[nvm]:
https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating
[nvm-windows]: https://github.com/coreybutler/nvm-windows
[org]: https://github.com/open-telemetry
To learn how to contribute new content and fixes to this project, see
[Contributing](https://opentelemetry.io/docs/contributing/), which includes a
style guide and useful information on the review process.
23 changes: 14 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,16 @@ to the registry][].

## Contributing

We have curated some issues with the tags [help wanted][] and [good first
issue][]. This should allow you to quickly find a place to contribute. See [CONTRIBUTING.md][]
for more information.
See the [Contributing](https://opentelemetry.io/docs/contributing) page on our
docs.

## Found a security issue?

If you discover a security issue, read the
[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy)
before opening an issue.

## Meetings

We, the OTel Communications SIG, meet every two weeks on Monday at 10:00 PT.
Check out the [OpenTelemetry community calendar][] for the Zoom link and any
Expand All @@ -38,6 +45,8 @@ updates to this schedule.
Meeting notes are available as a public [Google doc][]. If you have trouble accessing
the doc, get in touch in the `#otel-comms` channel on [Slack][].

## Roles

Here is a list of community roles with current and previous members:

- Approvers: [@open-telemetry/docs-approvers][]
Expand Down Expand Up @@ -82,16 +91,12 @@ contributed][contributors]!
[contributing.md]: CONTRIBUTING.md
[contributors]:
https://github.com/open-telemetry/opentelemetry.io/graphs/contributors
[hugo]: https://gohugo.io
[netlify]: https://netlify.com
[opentelemetry]: https://opentelemetry.io
[registry]: https://opentelemetry.io/ecosystem/registry/
[opentelemetry community calendar]:
https://calendar.google.com/calendar/embed?src=google.com_b79e3e90j7bbsa2n2p5an5lf60%40group.calendar.google.com
[help wanted]:
https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22
[good first issue]:
https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
[google doc]:
https://docs.google.com/document/d/1wW0jLldwXN8Nptq2xmgETGbGn9eWP8fitvD5njM-xZY/edit?usp=sharing
[slack]: https://slack.cncf.io/
[hugo]: https://gohugo.io
[netlify]: https://netlify.com
Loading
Loading