ceph/src/jaegertracing/opentelemetry-cpp/CONTRIBUTING.md

   1 # Contributing to opentelemetry-cpp
   2
   3 The OpenTelemetry C/C++ special interest group (SIG) meets regularly. See the
   4 OpenTelemetry [community](https://github.com/open-telemetry/community#cc-sdk)
   5 repo for information on this and other language SIGs.
   6
   7 See the [public meeting
   8 notes](https://docs.google.com/document/d/1i1E4-_y4uJ083lCutKGDhkpi3n4_e774SBLi9hPLocw/edit)
   9 for a summary description of past meetings. To request edit access, join the
  10 meeting or get in touch on
  11 [Slack](https://cloud-native.slack.com/archives/C01N3AT62SJ).
  12
  13 See the [community membership
  14 document](https://github.com/open-telemetry/community/blob/main/community-membership.md)
  15 on how to become a
  16 [**Member**](https://github.com/open-telemetry/community/blob/main/community-membership.md#member),
  17 [**Approver**](https://github.com/open-telemetry/community/blob/main/community-membership.md#approver)
  18 and
  19 [**Maintainer**](https://github.com/open-telemetry/community/blob/main/community-membership.md#maintainer).
  20
  21 ## Development
  22
  23 OpenTelemetry C++ uses the [Google naming
  24 convention](https://google.github.io/styleguide/cppguide.html#Naming).
  25
  26 Code is formatted automatically and enforced by CI.
  27
  28 ### Build and Run Code Examples
  29
  30 Note: these instructions apply to examples configured with Bazel, see
  31 example-specific documentation for other build automation tools.
  32
  33 Install the latest bazel version by following the steps listed
  34 [here](https://docs.bazel.build/versions/master/install.html).
  35
  36 Select an example of interest from the [examples
  37 folder](https://github.com/open-telemetry/opentelemetry-cpp/tree/main/examples).
  38 Inside each example directory is a `BUILD` file containing instructions for
  39 Bazel. Find the binary name of your example by inspecting the contents of this
  40 `BUILD` file.
  41
  42 Build the example from the root of the opentelemetry-cpp directory using Bazel.
  43 Replace `<binary name>` with the identifier found in the previous step:
  44
  45 ```sh
  46 bazel build //examples/<example directory name>:<binary name>
  47 ```
  48
  49 Run the resulting executable to see telemetry from the application as it calls
  50 the instrumented library: </li>
  51
  52 ```sh
  53 bazel-bin/examples/<example directory name>/<binary name>
  54 ```
  55
  56 For instance, building and running the `simple` example can be done as follows:
  57
  58 ```sh
  59 bazel build //examples/simple:example_simple
  60 bazel-bin/examples/simple/example_simple
  61 ```
  62
  63 ## Pull Requests
  64
  65 ### How to Send Pull Requests
  66
  67 Everyone is welcome to contribute code to `opentelemetry-cpp` via GitHub pull
  68 requests (PRs).
  69
  70 To create a new PR, fork the project in GitHub and clone the upstream repo:
  71
  72 ```sh
  73 git clone --recursive https://github.com/open-telemetry/opentelemetry-cpp.git
  74 ```
  75
  76 Add your fork as a remote:
  77
  78 ```sh
  79 git remote add fork https://github.com/YOUR_GITHUB_USERNAME/opentelemetry-cpp.git
  80 ```
  81
  82 If you haven't, make sure you are loading the submodules required to build
  83 OpenTelemetry
  84
  85 ```sh
  86 git submodule init
  87 git submodule update
  88 ```
  89
  90 Check out a new branch, make modifications and push the branch to your fork:
  91
  92 ```sh
  93 git checkout -b feature
  94 # edit files
  95 tools/format.sh
  96 git commit
  97 git push fork feature
  98 ```
  99
 100 If you made changes to the Markdown documents (`*.md` files), install the latest
 101 [`markdownlint-cli`](https://github.com/igorshubovych/markdownlint-cli) and run:
 102
 103 ```sh
 104 markdownlint .
 105 ```
 106
 107 Open a pull request against the main `opentelemetry-cpp` repo.
 108
 109 To run tests locally, please read the [CI instructions](ci/README.md).
 110
 111 ### How to Receive Comments
 112
 113 * If the PR is not ready for review, please put `[WIP]` in the title, tag it as
 114   `work-in-progress`, or mark it as
 115   [`draft`](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
 116 * Make sure [CLA](https://identity.linuxfoundation.org/projects/cncf) is signed
 117   and CI is clear.
 118 * For non-trivial changes, please update the [CHANGELOG](./CHANGELOG.md).
 119
 120 ### How to Get PRs Merged
 121
 122 A PR is considered to be **ready to merge** when:
 123
 124 * It has received two approvals with at least one approval from
 125   [Approver](https://github.com/open-telemetry/community/blob/main/community-membership.md#approver)
 126   /
 127   [Maintainer](https://github.com/open-telemetry/community/blob/main/community-membership.md#maintainer)
 128   (at different company).
 129 * A pull request opened by an Approver / Maintainer can be merged with only one
 130   approval from  Approver / Maintainer (at different company).
 131 * Major feedback items/points are resolved.
 132 * It has been open for review for at least one working day. This gives people
 133   reasonable time to review.
 134 * Trivial changes (typo, cosmetic, doc, etc.) don't have to wait for one day.
 135 * Urgent fixes can take exceptions as long as it has been actively communicated.
 136
 137 Any Maintainer can merge the PR once it is **ready to merge**. Maintainer can
 138 make conscious judgement to merge pull requests which have not strictly met
 139 above mentioned requirements.
 140
 141 If a PR has been stuck (e.g. there are lots of debates and people couldn't agree
 142 on each other), the owner should try to get people aligned by:
 143
 144 * Consolidating the perspectives and putting a summary in the PR. It is
 145   recommended to add a link into the PR description, which points to a comment
 146   with a summary in the PR conversation
 147 * Stepping back to see if it makes sense to narrow down the scope of the PR or
 148   split it up.
 149
 150 If none of the above worked and the PR has been stuck for more than 2 weeks, the
 151 owner should bring it to the OpenTelemetry C++ SIG meeting. See
 152 [README.md](README.md#contributing) for the meeting link.
 153
 154 ## Design Choices
 155
 156 As with other OpenTelemetry clients, opentelemetry-cpp follows the
 157 [opentelemetry-specification](https://github.com/open-telemetry/opentelemetry-specification).
 158
 159 It's especially valuable to read through the [library
 160 guidelines](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/library-guidelines.md).
 161
 162 ## Useful Resources
 163
 164 Hi! If you’re looking at this document, these resources will provide you the
 165 knowledge to get started as a newcomer to the OpenTelemetry project. They will
 166 help you understand the OpenTelemetry Project, its components, and specifically
 167 the C++ repository.
 168
 169 ### Reading Resources
 170
 171 * Medium
 172   [article](https://medium.com/opentelemetry/how-to-start-contributing-to-opentelemetry-b23991ad91f4)
 173   (October 2019) on how to start contributing to the OpenTelemetry project.
 174 * Medium
 175   [article](https://medium.com/opentelemetry/opentelemetry-beyond-getting-started-5ac43cd0fe26)
 176   (January 2020) describing the overarching goals and use cases for
 177   OpenTelemetry.
 178
 179 ### Relevant Documentation
 180
 181 * [OpenTelemetry
 182   Specification](https://github.com/open-telemetry/opentelemetry-specification)
 183   * The OpenTelemetry Specification describes the requirements and expectations
 184     of for all OpenTelemetry implementations.
 185
 186 * Read through the OpenTelemetry C++ documentation
 187   * The
 188     [API](https://opentelemetry-cpp.readthedocs.io/en/latest/api/api.html)
 189     and
 190     [SDK](https://opentelemetry-cpp.readthedocs.io/en/latest/sdk/sdk.html)
 191     documentation provides a lot of information on what the classes and their
 192     functions are used for.
 193
 194 Please contribute! You’re welcome to add more information if you come across any
 195 helpful resources.