Skip to content

Commit

Permalink
Add style guide and basic contribution section (#3651)
Browse files Browse the repository at this point in the history
  • Loading branch information
@theletterf
theletterf committed Jan 11, 2024
1 parent f8a7ec7 commit 243aa95
Show file tree
Hide file tree
Showing 8 changed files with 901 additions and 181 deletions.
163 changes: 40 additions & 123 deletions CONTRIBUTING.md
View file
@@ -1,46 +1,53 @@
# Contributing to OpenTelemetry.io

Thanks for your interest in contributing to
[OpenTelemetry.io](https://opentelemetry.io/)! Here are a few general guidelines
on contributing and reporting bugs that we ask you to review. Following these
guidelines helps to communicate that you respect the time of the contributors
managing and developing this open source project. In return, they 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.

Note that all of your interactions in the project are subject to our
**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 creation of issues or pull requests, commenting on issues or pull
requests, and extends to all interactions in any real-time space e.g., Slack,
Discord, etc.
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

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

## Found a security issue?
### Found a security issue?

If you discover a security issue, **do not** report it through GitHub. Instead,
follow the steps in our
[Security Policy](https://github.com/open-telemetry/opentelemetry.io/security/policy).
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?
### Found a problem?

If you find a problem with the content of this repository, or you would like to
request an enhancement, [create an issue][new-issue].
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, please ensure that the issue was not already
reported or fixed by searching through our
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 clear a
description, as much relevant information as possible, and, if possible, a test
case.
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?
### 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
Expand All @@ -59,64 +66,11 @@ 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.

## Sending Pull Requests

Enhancements and fixes to the website are most welcome!

Before sending a new [pull request][pr] (PR), take a look at existing
[pull requests](https://github.com/open-telemetry/opentelemetry.io/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc)
and
[issues](https://github.com/open-telemetry/opentelemetry.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)
to see if the proposed change or fix has been discussed in the past, or if the
change was already implemented but not yet released.

### Quick fixes

For small changes to a single file, you can edit directly in GitHub by clicking
**Edit this file** button. After forking the repository, follow the instructions
in [Editing files][].

However, formatting may still be needed, like reducing line lengths in the
edited file. The options for fixing formatting are:

- Checking out the project and running the CLI scripts mentioned in
[Submitting a change](#submitting-a-change).
- Commenting `/fix:format` on your pull request to trigger an automated script.
This requires a unique branch name, which can be edited under _View all
branches_ in your fork.

For larger fixes, follow the
[instructions to setup a development environment](#development) below.

### PR Guidelines

Before a PR gets merged, it will sometimes require a few iterations of
review-and-edit. To help us and yourself make this process as easy as possible,
we ask that adhere to the following:

- If your PR isn't a [quick fix](#quick-fixes), then **work from a fork**: Click
the [Fork](https://github.com/open-telemetry/opentelemetry.io/fork) button at
the top of the repository and clone the fork locally. When you are ready,
raise a PR with the upstream repository.
- **Do not work from the `main`** branch of your fork, but create a PR-specific
branch.
- Ensure that maintainers are
[allowed to apply changes to your pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork).

### Merge requirements
## Contributor's guide

- No “changes requested” reviews by approvers, maintainers, technical committee
members, or subject matter experts
- No unresolved conversations
- Approved by at least one approver
- No failing PR checks
- PR branch is up-to-date with the base branch

> **Important**
>
> Do not worry too much about failing PR checks! Community members will help you
> to get them fixed, by either providing you with instructions how to fix them
> or by fixing them on your behave.
To learn how to contribute fixes and new content to this project, read the
[Contributor's guide](/content/en/docs/contributing), which includes a style
guide and useful information on the review process.

## Development

Expand Down Expand Up @@ -219,24 +173,6 @@ The website is built from the following content:
[content-modules]:
https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules

### Submitting a change

Before submitting a change to the repository, run the following command and
address any reported issues. Also commit any files changed by the `fix` script:

```sh
npm run test-and-fix
```

To separately test and fix issues with your files, run:

```sh
npm run test # checks but does not update any files
npm run fix # may update files
```

To list available NPM scripts, run `npm run`.

### Submodule changes

If you change any content inside of a [content-modules][] submodule, then you'll
Expand All @@ -255,17 +191,6 @@ submodule itself.
> You'll also need to `git fetch --unshallow` the submodule before you can
> submit a PR. Alternatively, set `DEPTH=100` and re-fetch submodules.
### Site deploys and PR previews

If you submit a PR, Netlify will create a [deploy preview][] so that you can
review your changes. Once your PR is merged, Netlify deploys the updated site to
the production server.

> **Note**: PR previews include _draft pages_, but production builds do not.
To see deploy logs and more, visit project's [dashboard][] -- Netlify login
required.

## Approver and Maintainer practices

This last section includes guidelines and some common practices used by
Expand Down Expand Up @@ -302,18 +227,12 @@ approvers and maintainers while doing code reviews:
[.nvmrc]: .nvmrc
[clone]:
https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository
[dashboard]: https://app.netlify.com/sites/opentelemetry/overview
[deploy preview]:
https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/
[editing files]:
https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files
[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
Expand All @@ -323,5 +242,3 @@ approvers and maintainers while doing code reviews:
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
[pr]:
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
72 changes: 17 additions & 55 deletions README.md
View file
@@ -1,78 +1,42 @@
# <img src="https://opentelemetry.io/img/logos/opentelemetry-logo-nav.png" alt="OTel logo" width="45"> OpenTelemetry.io

This is the source repository for the [OpenTelemetry][] website, project
documentation and blog. The site is [built][contributing.md] using [Hugo][] and
hosted on [Netlify][].
documentation, and blog. The site is [built][contributing.md] using [Hugo][] and
is hosted on [Netlify][].

## Get involved

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

If you are new to OpenTelemetry and just get started with it, you are in a
perfect position to help us get better: the website and documentation is the
entry point for newcomers like you, so if something is unclear or something is
missing [let us know][]!

Read on to learn about other ways on how you can help.

## Adding a project to the OpenTelemetry [Registry]

For details, see [Adding to the registry][].

## Submitting a blog post

You can submit a blog post either by forking this repository and writing it
locally or by using the GitHub UI. In both cases we ask you to follow the
instructions provided by the [blog post template](archetypes/blog.md).

**Note**: Before writing a blog post, please ask yourself, if your content also
might be a good addition to the documentation. If the answer is yes, create a
new issue/PR with your content to get it added to the docs.
missing [let us know][].

### Fork & Write locally
### Submit a blog post

Follow the [setup instructions][contributing.md] then, to create a skeletal blog
post, run the following command from the repository root:
For guidance on how to write and submit a blog post, see
[Submit a blog post](/content/en/docs/contributing/blog).

```sh
npx hugo new content/en/blog/2023/short-name-for-post.md
```
### Add a project to the OpenTelemetry [Registry]

If your post will have images or other assets, instead run:

```sh
npx hugo new content/en/blog/2023/short-name-for-post/index.md
```

Edit the markdown file at the path you provided in the previous command. The
file is initialized from the blog-post starter under [archetypes](archetypes).

Put assets, if any, like images into the folder created.

Once your post is ready, submit it through a [pull request][].

### Using the GitHub UI

- Go to the [blog post template](archetypes/blog.md) and click on
`Copy raw content` at the top right of the menu.
- [Create a new file](https://github.com/open-telemetry/opentelemetry.io/new/main).
- Paste the content from the template.
- Name your file, e.g.
`content/en/blog/2022/short-name-for-your-blog-post/index.md`
- Start editing the markdown file.
- Once your post is ready click on `Propose changes` at the bottom.
For details on how to add a project to the OpenTelemetry Registry, see [Adding
to the registry][].

## Contributing

See [CONTRIBUTING.md][].

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
issue][]. This should allow you to quickly find a place to contribute. See
[CONTRIBUTING.md][] for more information.

We (OTel Comms SIG) meet every two weeks on Monday at 9:00 PT. Check out the
We, the OTel Comms SIG, meet every two weeks on Monday at 9:00 PT. Check out the
[OpenTelemetry community calendar][] for the Zoom link and any updates to this
schedule.

Meeting notes are available as a public [Google doc][]. If you have trouble
accessing the doc, please get in touch on [Slack][].
accessing the doc, get in touch on [Slack][].

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

Expand Down Expand Up @@ -121,8 +85,6 @@ already contributed][contributors]!
[hugo]: https://gohugo.io
[netlify]: https://netlify.com
[opentelemetry]: https://opentelemetry.io
[pull request]:
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
[registry]: https://opentelemetry.io/ecosystem/registry/
[opentelemetry community calendar]:
https://calendar.google.com/calendar/embed?src=google.com_b79e3e90j7bbsa2n2p5an5lf60%40group.calendar.google.com
Expand Down

0 comments on commit 243aa95

Please sign in to comment.