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.

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

Remove hard line breaks #564

Closed
wants to merge 11 commits into from
7 changes: 3 additions & 4 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
# Changelog

Please update changelog as part of any significant pull request. Place short
description of your change into "Unreleased" section. As part of release
process content of "Unreleased" section content will generate release notes for
the release.
Please update changelog as part of any significant pull request.
Place short description of your change into "Unreleased" section.
As part of release process content of "Unreleased" section content will generate release notes for the release.

## Unreleased

Expand Down
39 changes: 10 additions & 29 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,30 +2,22 @@

Welcome to OpenTelemetry specifications repository!

Before you start - see OpenTelemetry general
[contributing](https://github.com/open-telemetry/community/blob/master/CONTRIBUTING.md)
requirements and recommendations.
Before you start - see OpenTelemetry general [contributing](https://github.com/open-telemetry/community/blob/master/CONTRIBUTING.md) requirements and recommendations.

## Sign the CLA

Before you can contribute, you will need to sign the [Contributor License
Agreement](https://identity.linuxfoundation.org/projects/cncf).
Before you can contribute, you will need to sign the [Contributor License Agreement](https://identity.linuxfoundation.org/projects/cncf).

## Proposing a change

Significant changes should go through the [RFC process](https://github.com/open-telemetry/rfcs).

## Writing specs

Specification is written in markdown format. Please make sure files are rendered
OK on GitHub.
Specification is written in markdown format.
Please make sure files are rendered OK on GitHub.

Be sure to clearly define the specification requirements using the key words
defined in [BCP 14](https://tools.ietf.org/html/bcp14)
[[RFC2119](https://tools.ietf.org/html/rfc2119)]
[[RFC8174](https://tools.ietf.org/html/rfc8174)] while making sure to heed the
guidance laid out in [RFC2119](https://tools.ietf.org/html/rfc2119) about the
sparing use of imperatives:
Be sure to clearly define the specification requirements using the key words defined in [BCP 14](https://tools.ietf.org/html/bcp14) [[RFC2119](https://tools.ietf.org/html/rfc2119)] [[RFC8174](https://tools.ietf.org/html/rfc8174)] while making sure to heed the guidance laid out in [RFC2119](https://tools.ietf.org/html/rfc2119) about the sparing use of imperatives:

> Imperatives of the type defined in this memo must be used with care
> and sparingly. In particular, they MUST only be used where it is
Expand All @@ -35,21 +27,13 @@ sparing use of imperatives:
> on implementors where the method is not required for
> interoperability.

It is important to build a specification that is clear and useful, not
one that is needlessly restrictive and complex.
It is important to build a specification that is clear and useful, not one that is needlessly restrictive and complex.

### Markdown style

Markdown files should be properly formatted before a pull request is sent out.
In this repository we follow the
[markdownlint rules](https://github.com/DavidAnson/markdownlint#rules--aliases)
with some customizations. See [markdownlint](.markdownlint.yaml) or
[settings](.vscode/settings.json) for details.

We highly encourage to use line breaks in markdown files at `80` characters
wide. There are tools that can do it for you effectively. Please submit proposal
to include your editor settings required to enable this behavior so the out of
the box settings for this repository will be consistent.
In this repository we follow the [markdownlint rules](https://github.com/DavidAnson/markdownlint#rules--aliases) with some customizations.
See [markdownlint](.markdownlint.yaml) or [settings](.vscode/settings.json) for details.

To check for style violations, use

Expand All @@ -59,11 +43,8 @@ gem install mdl
mdl -c .mdlrc .
```

To fix style violations, follow the
[instruction](https://github.com/DavidAnson/markdownlint#optionsresultversion)
with the Node version of markdownlint. If you are using Visual Studio Code,
you can also use the `fixAll` command of the
[vscode markdownlint extension](https://github.com/DavidAnson/vscode-markdownlint).
To fix style violations, follow the [instruction](https://github.com/DavidAnson/markdownlint#optionsresultversion) with the Node version of markdownlint.
If you are using Visual Studio Code, you can also use the `fixAll` command of the [vscode markdownlint extension](https://github.com/DavidAnson/vscode-markdownlint).

### Misspell check

Expand Down
74 changes: 26 additions & 48 deletions issue-management.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,23 @@
# Issue Management for OpenTelemetry

It's an important community goal for OpenTelemetry that our members find the backlogs
to be responsive, and easy to take part in. Shared practices will simplify collaboration
and engagement as well as help standardize on automation and overall project management.
It's an important community goal for OpenTelemetry that our members find the backlogs to be responsive, and easy to take part in.
Shared practices will simplify collaboration and engagement as well as help standardize on automation and overall project management.

SIGs are encouraged to experiment with labels and backlog management procedures,
including project board. This document only covers the bare bones of issue management
which should work the same across all SIGs, to help maintain a responsive backlog and
allow us to track work across all projects in a similar manner.
SIGs are encouraged to experiment with labels and backlog management procedures, including project board.
This document only covers the bare bones of issue management which should work the same across all SIGs, to help maintain a responsive backlog and allow us to track work across all projects in a similar manner.

## Roles

- OP:
- Original Poster. This is the person who has opened or posted the issue.
- Maintainer (aka Triager, or anyone performing that role):
- Person who is triaging the issue by determining its workability. This person is
responsible for getting the tickets to one of two stages - 1) `help-wanted`
2) `will-not-fix`. They are responsible for triaging by working with the OP to get
additional information as needed and analyzing the issue and adding relevant
details/information/guidance that would be helpful to the resolution of the issue.
- Person who is triaging the issue by determining its workability.
This person is responsible for getting the tickets to one of two stages - 1) `help-wanted` 2) `will-not-fix`.
They are responsible for triaging by working with the OP to get additional information as needed and analyzing the issue and adding relevant details/information/guidance that would be helpful to the resolution of the issue.
- Collaborator:
- Person(s) that are actually doing the work related to the ticket. Once work is done,
they work with the Reviewer to get feedback implemented and complete the work. They
are responsible for making sure issue status labels are up to date.
- Person(s) that are actually doing the work related to the ticket.
Once work is done, they work with the Reviewer to get feedback implemented and complete the work.
They are responsible for making sure issue status labels are up to date.
- Reviewer:
- Person whose Approval is needed to merge the PR.

Expand All @@ -39,51 +34,34 @@ allow us to track work across all projects in a similar manner.
- The Maintainer can also label the issue as
- `URGENT` (for critical issues)
- `help-wanted` for issues which require work and have no one assigned
- Once a Collaborator is assigned, please remove `help-wanted` and add `wip` to
the issue.
- Once a Collaborator is assigned, please remove `help-wanted` and add `wip` to the issue.

## Closing an Issue

- Review criteria:
- For interface and design changes: 2 approvals - which must be from reviewers
who work at different companies than the Collaborator.
- For interface and design changes: 2 approvals - which must be from reviewers who work at different companies than the Collaborator.
- For smaller or internal changes: 1 approval from a different company.
- For `URGENT` issues:
- Collaborator: please provide an initial assessment of the issues to OP ASAP or
within 1 business day, whichever is earlier.
- Reviewer: please review and provide feedback ASAP or within 1 business day,
whichever is earlier.
- Collaborator: please provide an update and/or response to each review comment ASAP
or within 1 business day, whichever is sooner. Merge should happen as soon as
review criteria are met.
- Collaborator: please provide an initial assessment of the issues to OP ASAP or within 1 business day, whichever is earlier.
- Reviewer: please review and provide feedback ASAP or within 1 business day, whichever is earlier.
- Collaborator: please provide an update and/or response to each review comment ASAP or within 1 business day, whichever is sooner. Merge should happen as soon as review criteria are met.
- For non-`URGENT` issues
- Collaborator: please provide an initial response or assessment of the issue to
OP within 3 business days.
- Collaborator: please provide an initial response or assessment of the issue to OP within 3 business days.
- Reviewer: please review and provide feedback within 3 business days.
- Collaborator: please provide an update and/or response to each review comment
within 3 business days. Once all review comments are resolved, please allow
1-2 business days for others to raise additional comments/questions, unless
the changes are fixing typos, bugs, documentation, test enhancements, or
implementing already discussed design.
- Collaborator: please provide an update and/or response to each review comment within 3 business days.
Once all review comments are resolved, please allow 1-2 business days for others to raise additional comments/questions, unless the changes are fixing typos, bugs, documentation, test enhancements, or implementing already discussed design.

When closing an issue that we `will-not-fix` or we believe need no further
action, please provide the rationale for closing, and indicate that OP can
re-open for discussion if there are additional info, justification and
questions.
When closing an issue that we `will-not-fix` or we believe need no further action, please provide the rationale for closing, and indicate that OP can re-open for discussion if there are additional info, justification and questions.

## When Issues Get Stuck

Some issues are not directly related to a particular code change. If an
issue is worth considering in the issue backlog, but not scoped clearly
enough for work to begin, then please label it `needs-discussion`.
Some issues are not directly related to a particular code change.
If an issue is worth considering in the issue backlog, but not scoped clearly enough for work to begin, then please label it `needs-discussion`.

- When possible, move the discussion forward by using tests and code examples.
- If discussion happens elsewhere, record relevant meeting notes into the
issue.
- When an agreement is made, clearly summarize the decision, and list any
resulting action items which need to be addressed.
- If discussion happens elsewhere, record relevant meeting notes into the issue.
- When an agreement is made, clearly summarize the decision, and list any resulting action items which need to be addressed.

If an issue is stuck because someone is not responding, please add the `stale`
label. It is possible to automate this. E.g. <https://github.com/apps/stale>
The minimum time elapsed before the `stale` label is applied is proposed to be
one week.
If an issue is stuck because someone is not responding, please add the `stale` label.
It is possible to automate this.
E.g. <https://github.com/apps/stale> The minimum time elapsed before the `stale` label is applied is proposed to be one week.
21 changes: 8 additions & 13 deletions specification/concurrency.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,17 @@
# Concurrency and Thread-Safety of OpenTelemetry API

For languages which support concurrent execution the OpenTelemetry APIs provide
specific guarantees and safeties. Not all of API functions are safe to
be called concurrently. Function and method documentation must explicitly
specify whether it is safe or no to make concurrent calls and in what
situations.
For languages which support concurrent execution the OpenTelemetry APIs provide specific guarantees and safeties.
Not all of API functions are safe to be called concurrently.
Function and method documentation must explicitly specify whether it is safe or no to make concurrent calls and in what situations.

The following are general recommendations of concurrent call safety of
specific subsets of the API.
The following are general recommendations of concurrent call safety of specific subsets of the API.

**Tracer** - all methods are safe to be called concurrently.

**SpanBuilder** - It is not safe to concurrently call any methods of the
same SpanBuilder instance. Different instances of SpanBuilder can be safely
used concurrently by different threads/coroutines, provided that no single
SpanBuilder is used by more than one thread/coroutine.
**SpanBuilder** - It is not safe to concurrently call any methods of the same SpanBuilder instance.
Different instances of SpanBuilder can be safely used concurrently by different threads/coroutines, provided that no single SpanBuilder is used by more than one thread/coroutine.

**Span** - All methods of Span are safe to be called concurrently.

**Link** - Links are immutable and is safe to be used concurrently. Lazy
initialized links must be implemented to be safe to be called concurrently.
**Link** - Links are immutable and is safe to be used concurrently.
Lazy initialized links must be implemented to be safe to be called concurrently.
Loading