Skip to content

Commit

Permalink
Merge 04358a3 into 5259a0b
Browse files Browse the repository at this point in the history
  • Loading branch information
haddasbronfman authored Aug 17, 2023
2 parents 5259a0b + 04358a3 commit 2a3a684
Show file tree
Hide file tree
Showing 2 changed files with 37 additions and 0 deletions.
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ For experimental package changes, see the [experimental CHANGELOG](experimental/

### :books: (Refine Doc)

* docs(guidelines): add dependencies guidelines [#4040](https://github.com/open-telemetry/opentelemetry-js/pull/4040)

### :house: (Internal)

## 1.15.2
Expand Down
35 changes: 35 additions & 0 deletions GUIDELINES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# OpenTelemetry JS Code Contribution Guide

This document outlines the essential guidelines for contributing code to the OpenTelemetry JS repository. These guidelines are designed to ensure consistency, stability, and the highest quality of code across the project.

## Dependencies

This section refers to `"dependencies"` and `"devDependencies"` entries in `package.json` file.
> [!IMPORTANT]
> Not all libraries follow [Semantic Versioning](https://semver.org/). Even those who do might occasionally introduce breaking changes due to human errors. Exceptions to the guidelines in this document MAY be granted by Approvers or Maintainers to work around this.
### Development Dependencies

`"devDependencies"` SHOULD be pinned to reduce the risk of autobreaking the build. Since we cannot use the `package-lock.json` file (because the libraries are distributed without it), control over the version our contributors will get is limited. By using pinned versions, we prevent potential disruptions caused by unpinned versions.

**Example:** `^1.2.3` might inadvertently lead to version `1.2.6` which includes unintended breaking changes).

> [!NOTE]
> As this approach might leave our project with outdated tooling, we adopt `renovate-bot`. This automated dependency update tool proactively opens pull requests upon the release of new patch/minor/major versions. The complete configuration for renovate-bot can be found in [renovate.json](./renovate.json) file.
### @opentelemetry/* dependencies

All packages from the `@opentelemetry/` namespace MUST have the same pinned version, as these dependencies are automatically updated on each release by lerna.

**Example:** all packages under `packages/` should consistently maintain the same version, as should those under `experimental/packages/`.

An exception is granted for dependencies on `@opentelemetry/api`, which, if used by the package SHOULD NOT be included as a `dependency`. `@opentelemetry/api` SHOULD be included as a `peerDependency` instead. The version range of the `peerDependency` SHOULD reflect the minimum supported, and SHOULD NOT allow versions greater than the latest released minor version.

### Third-Party Library Dependencies

Packages categorized as third-party and listed under the `"dependencies"` section (e.g., @grpc/grpc-js, @grpc/proto-loader, shimmer, etc.) should remain unpinned and utilize the caret (`^`) symbol. This approach offers several advantages:

* Our users could get bug fixes of those 3rd-party packages easily, without waiting for us to update our library.
* In cases where multiple packages have dependencies on different versions of the same package, npm will opt for the most recent version, saving space and preventing potential disruptions.

It's important to acknowledge that this approach does expose users to potential breaking changes arising from either human error or libraries that do not strictly follow to semver conventions. This trade-off is an inherent aspect of this approach.

0 comments on commit 2a3a684

Please sign in to comment.