Skip to content

Commit

Permalink
Improve contributing guidelines (#1354)
Browse files Browse the repository at this point in the history
  • Loading branch information
cijothomas authored Nov 9, 2023
1 parent d7e4629 commit 4f1c3a2
Showing 1 changed file with 48 additions and 22 deletions.
70 changes: 48 additions & 22 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,22 @@
# Contributing to opentelemetry-rust

The Rust special interest group (SIG) meets regularly. See the
OpenTelemetry
[community](https://github.com/open-telemetry/community#implementation-sigs)
repo for information on this and other language SIGs.

See the [public meeting
notes](https://docs.google.com/document/d/1tGKuCsSnyT2McDncVJrMgg74_z8V06riWZa0Sr79I_4/edit)
for a summary description of past meetings. To request edit access,
join the meeting or get in touch on
The Rust special interest group (SIG) meets weekly on Tuesdays at 8 AM Pacific
Time (16:00 UTC). The meeting is subject to change depending on contributors'
availability. Check the [OpenTelemetry community
calendar](https://calendar.google.com/calendar/embed?src=google.com_b79e3e90j7bbsa2n2p5an5lf60%40group.calendar.google.com)
for specific dates and for Zoom meeting links. "OTel Rust SIG" is the name of
meeting for this group.

Meeting notes are available as a public [Google
doc](https://docs.google.com/document/d/1tGKuCsSnyT2McDncVJrMgg74_z8V06riWZa0Sr79I_4/edit).
If you have trouble accessing the doc, please get in touch on
[Slack](https://cloud-native.slack.com/archives/C03GDP0H023).

The meeting is open for all to join. We invite everyone to join our meeting,
regardless of your experience level. Whether you're a seasoned OpenTelemetry
developer, just starting your journey, or simply curious about the work we do,
you're more than welcome to participate!

## Pull Requests

### Prerequisites
Expand Down Expand Up @@ -64,20 +70,32 @@ the repo to catch any issues locally.

### How to Receive Comments

* If the PR is not ready for review, please put `[WIP]` in the title,
tag it as `work-in-progress`, or mark it as
[`draft`](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
* Make sure CLA is signed and CI is clear.
* If the PR is not ready for review, please put `[WIP]` in the title or mark it
as [`draft`](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
* Make sure CLA is signed and all required CI checks are clear.
* Submit small, focused PRs addressing a single concern/issue.
* Make sure the PR title reflects the contribution.
* Write a summary that helps understand the change.
* Include usage examples in the summary, where applicable.
* Include benchmarks (before/after) in the summary, for contributions that are
performance enhancements.

### How to Get PRs Merged

A PR is considered to be **ready to merge** when:

* It has received approval from Collaborators/Maintainers.
* Major feedback is resolved.
* It has received approval from
[Approvers](https://github.com/open-telemetry/community/blob/main/community-membership.md#approver).
/
[Maintainers](https://github.com/open-telemetry/community/blob/main/community-membership.md#maintainer).
* Major feedbacks are resolved.

Any Collaborator/Maintainer can merge the PR once it is **ready to
merge**.
Any Maintainer can merge the PR once it is **ready to merge**. Note, that some
PRs may not be merged immediately if the repo is in the process of a release and
the maintainers decided to defer the PR to the next release train. Also,
maintainers may decide to wait for more than one approval for certain PRs,
particularly ones that are affecting multiple areas, or topics that may warrant
more discussion.

## Design Choices

Expand All @@ -102,23 +120,23 @@ language rather than conform to specific API names or argument
patterns in the spec.

For a deeper discussion, see:
https://github.com/open-telemetry/opentelemetry-specification/issues/165
<https://github.com/open-telemetry/opentelemetry-specification/issues/165>

### Error Handling
Currently, the Opentelemetry Rust SDK has two ways to handle errors. In the situation where errors are not allowed to return. One should call global error handler to process the errors. Otherwise, one should return the errors.

Currently, the Opentelemetry Rust SDK has two ways to handle errors. In the situation where errors are not allowed to return. One should call global error handler to process the errors. Otherwise, one should return the errors.

The Opentelemetry Rust SDK comes with an error type `openetelemetry::Error`. For different function, one error has been defined. All error returned by trace module MUST be wrapped in `opentelemetry::trace::TraceError`. All errors returned by metrics module MUST be wrapped in `opentelemetry::metrics::MetricsError`.

For users that want to implement their own exporters. It's RECOMMENDED to wrap all errors from the exporter into a crate-level error type, and implement `ExporterError` trait.

### Priority of configurations

OpenTelemetry supports multiple ways to configure the API, SDK and other components. The priority of configurations is as follows:

- Environment variables
- Compiling time configurations provided in the source code



## Style Guide

* Run `cargo clippy --all` - this will catch common mistakes and improve
Expand All @@ -131,6 +149,7 @@ issues.
* Run `cargo test --all` - this will execute code and doc tests for all
projects in this workspace.
* Run `cargo bench` - this will run benchmarks to show performance
* Run `cargo bench` - this will run benchmarks to show performance
regressions

## Approvers and Maintainers
Expand Down Expand Up @@ -165,5 +184,12 @@ repo](https://github.com/open-telemetry/community/blob/master/community-membersh
[![contributors](https://contributors-img.web.app/image?repo=open-telemetry/opentelemetry-rust)](https://github.com/open-telemetry/opentelemetry-rust/graphs/contributors)

## FAQ

### Where should I put third party propagators/exporters, contrib or standalone crates?
As of now, the specification classify the propagators into three categories: Fully opened standards, platform-specific standards, proprietary headers. The conclusion is only the fully opened standards should live in SDK packages/repos. So here, only fully opened standards should live as independent crate. For more detail and discussion, see [this pr](https://github.com/open-telemetry/opentelemetry-specification/pull/1144).

As of now, the specification classify the propagators into three categories:
Fully opened standards, platform-specific standards, proprietary headers. The
conclusion is only the fully opened standards should live in SDK packages/repos.
So here, only fully opened standards should live as independent crate. For more
detail and discussion, see [this
pr](https://github.com/open-telemetry/opentelemetry-specification/pull/1144).

0 comments on commit 4f1c3a2

Please sign in to comment.