Clean up Contributing.md (#655)
* clean up contributing doc * fixed a missing period * clarify tags * minor tweak * address comments * Update CONTRIBUTING.md Co-authored-by: Sergey Kanzhelev <S.Kanzhelev@live.com> * Update CONTRIBUTING.md Co-authored-by: Sergey Kanzhelev <S.Kanzhelev@live.com> Co-authored-by: Sergey Kanzhelev <S.Kanzhelev@live.com>
This commit is contained in:
Reiley Yang
GitHub
parent
f4e18d5141
commit
ecb6928bb2
155
CONTRIBUTING.md
155
CONTRIBUTING.md
|
|
@ -1,46 +1,35 @@
|
|||
# Contributing
|
||||
# Contributing to opentelemetry-dotnet
|
||||
|
||||
## Report a bug or requesting feature
|
||||
The OpenTelemetry .NET special interest group (SIG) meets regularly. See the
|
||||
OpenTelemetry [community](https://github.com/open-telemetry/community#net-sdk)
|
||||
repo for information on this and other language SIGs.
|
||||
|
||||
Reporting bugs is an important contribution. Please make sure to include:
|
||||
See the [public meeting notes](https://docs.google.com/document/d/1yjjD6aBcLxlRazYrawukDgrhZMObwHARJbB9glWdHj8/edit?usp=sharing)
|
||||
for a summary description of past meetings. To request edit access, join the
|
||||
meeting or get in touch on [Gitter](https://gitter.im/open-telemetry/opentelemetry-dotnet).
|
||||
|
||||
- expected and actual behavior.
|
||||
- dotnet version that application is compiled on and running with (it may be
|
||||
different - for instance target framework was set to .NET 4.6 for
|
||||
compilation, but application is running on .NET 4.7.2).
|
||||
- exception call stack and other artifacts.
|
||||
- if possible - repro application and steps to reproduce.
|
||||
Even though, anybody can contribute, there are benefits of being a member of our community. See to the [community membership document](https://github.com/open-telemetry/community/blob/master/community-membership.md)
|
||||
on how to become a [**Member**](https://github.com/open-telemetry/community/blob/master/community-membership.md#member),
|
||||
[**Approver**](https://github.com/open-telemetry/community/blob/master/community-membership.md#approver)
|
||||
and [**Maintainer**](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer).
|
||||
|
||||
## How to contribute
|
||||
# Find a Buddy and get Started Quickly!
|
||||
|
||||
### Before you start
|
||||
If you are looking for someone to help you find a starting point and be a resource for your first contribution, join our
|
||||
Gitter and find a buddy!
|
||||
|
||||
Please read project contribution
|
||||
[guide](https://github.com/open-telemetry/community/blob/master/CONTRIBUTING.md)
|
||||
for general practices for OpenTelemetry project.
|
||||
1. Join [Gitter.im](https://gitter.im) and join our [chat room](https://gitter.im/open-telemetry/opentelemetry-dotnet).
|
||||
2. Post in the room with an introduction to yourself, what area you are
|
||||
interested in (check issues marked with [good first
|
||||
issue](https://github.com/open-telemetry/opentelemetry-dotnet/labels/good%20first%20issue)
|
||||
or [help wanted](https://github.com/open-telemetry/opentelemetry-dotnet/labels/help%20wanted)),
|
||||
and say you are looking for a buddy. We will match you with someone who has experience in that area.
|
||||
|
||||
### Fork
|
||||
Your OpenTelemetry buddy is your resource to talk to directly on all aspects of contributing to OpenTelemetry: providing
|
||||
context, reviewing PRs, and helping those get merged. Buddies will not be available 24/7, but is committed to responding
|
||||
during their normal contribution hours.
|
||||
|
||||
In the interest of keeping this repository clean and manageable, you should work from a fork. To create a fork, click the 'Fork' button at the top of the repository, then clone the fork locally using `git clone git@github.com:USERNAME/opentelemetry-dotnet.git`.
|
||||
|
||||
You should also add this repository as an "upstream" repo to your local copy, in order to keep it up to date. You can add this as a remote like so:
|
||||
```
|
||||
git remote add upstream https://github.com/open-telemetry/opentelemetry-dotnet.git
|
||||
|
||||
#verify that the upstream exists
|
||||
git remote -v
|
||||
```
|
||||
|
||||
To update your fork, fetch the upstream repo's branches and commits, then merge your master with upstream's master:
|
||||
```
|
||||
git fetch upstream
|
||||
git checkout master
|
||||
git merge upstream/master
|
||||
```
|
||||
|
||||
Remember to always work in a branch of your local copy, as you might otherwise have to contend with conflicts in master.
|
||||
|
||||
Please also see [GitHub workflow](https://github.com/open-telemetry/community/blob/master/CONTRIBUTING.md#github-workflow) section of general project contributing guide.
|
||||
## Development
|
||||
|
||||
### Prerequisites
|
||||
|
||||
|
|
@ -56,7 +45,7 @@ In all platforms, the requirements are:
|
|||
* Visual Studio 2017+, VS Code or JetBrains Rider
|
||||
* .NET Framework 4.6+
|
||||
|
||||
#### macOS or Linux
|
||||
#### MacOS or Linux
|
||||
|
||||
* Visual Studio for Mac, VS Code or JetBrains Rider
|
||||
|
||||
|
|
@ -69,7 +58,7 @@ Open `OpenTelemetry.sln` in your IDE of choice and follow normal development pro
|
|||
|
||||
To build from the command line you need `dotnet` version `3.1+`.
|
||||
|
||||
``` sh
|
||||
```sh
|
||||
dotnet build OpenTelemetry.sln
|
||||
```
|
||||
|
||||
|
|
@ -81,7 +70,7 @@ process.
|
|||
|
||||
To test from command line you need `dotnet` version `3.1+`.
|
||||
|
||||
``` sh
|
||||
```sh
|
||||
dotnet test OpenTelemetry.sln
|
||||
```
|
||||
|
||||
|
|
@ -91,21 +80,85 @@ To see test coverage, run `dotnet test` from a console window and you will see t
|
|||
|
||||
Or, after running the tests, open the file `TestResults\Results\index.htm` in a browser.
|
||||
|
||||
### Coding style
|
||||
## Pull Requests
|
||||
|
||||
### How to Send Pull Requests
|
||||
|
||||
Everyone is welcome to contribute code to `opentelemetry-dotnet` via GitHub
|
||||
pull requests (PRs).
|
||||
|
||||
To create a new PR, fork the project in GitHub and clone the upstream repo:
|
||||
|
||||
```sh
|
||||
$ git clone https://github.com/open-telemetry/opentelemetry-dotnet.git
|
||||
```
|
||||
|
||||
Add your fork as an origin:
|
||||
|
||||
```sh
|
||||
$ git remote add fork https://github.com/YOUR_GITHUB_USERNAME/opentelemetry-dotnet.git
|
||||
```
|
||||
|
||||
Run tests:
|
||||
|
||||
```sh
|
||||
dotnet test
|
||||
```
|
||||
|
||||
Check out a new branch, make modifications and push the branch to your fork:
|
||||
|
||||
```sh
|
||||
$ git checkout -b feature
|
||||
# edit files
|
||||
$ git commit
|
||||
$ git push fork feature
|
||||
```
|
||||
|
||||
Open a pull request against the main `opentelemetry-dotnet` repo.
|
||||
|
||||
### 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.
|
||||
|
||||
### How to Get PRs Merged
|
||||
|
||||
A PR is considered to be **ready to merge** when:
|
||||
* It has received approval from [Approvers](https://github.com/open-telemetry/community/blob/master/community-membership.md#approver).
|
||||
/ [Maintainers](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer).
|
||||
* Major feedbacks are resolved.
|
||||
* It has been open for review for at least one working day. This gives people
|
||||
reasonable time to review.
|
||||
* Trivial change (typo, cosmetic, doc, etc.) doesn't have to wait for one day.
|
||||
* Urgent fix can take exception as long as it has been actively communicated.
|
||||
|
||||
Any Maintainer can merge the PR once it is **ready to merge**. Note, that some PR may not be merged immediately if repo is being in process of a major release and the new feature doesn't fit it.
|
||||
|
||||
## Design Choices
|
||||
|
||||
As with other OpenTelemetry clients, opentelemetry-dotnet follows the
|
||||
[opentelemetry-specification](https://github.com/open-telemetry/opentelemetry-specification).
|
||||
|
||||
It's especially valuable to read through the [library guidelines](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/library-guidelines.md).
|
||||
|
||||
### Focus on Capabilities, Not Structure Compliance
|
||||
|
||||
OpenTelemetry is an evolving specification, one where the desires and
|
||||
use cases are clear, but the method to satisfy those uses cases are not.
|
||||
|
||||
As such, contributions should provide functionality and behavior that
|
||||
conforms to the specification, but the interface and structure is flexible.
|
||||
|
||||
It is preferable to have contributions follow the idioms of the 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
|
||||
|
||||
## Style Guide
|
||||
|
||||
This project includes a [`.editorconfig`](https://github.com/open-telemetry/opentelemetry-dotnet/blob/master/.editorconfig)
|
||||
file which is supported by all the IDEs/editor mentioned above.
|
||||
It works with the IDE/editor only and does not affect the actual build of the project.
|
||||
|
||||
This repository also includes a
|
||||
[_test_, _prod_ and _prod.loose_ _stylecop ruleset_](https://github.com/open-telemetry/opentelemetry-dotnet/tree/master/build) files.
|
||||
|
||||
These files are used to configure the _StyleCop.Analyzers_ which runs during build. Breaking the rules will result in a broken build.
|
||||
|
||||
### Proposing changes
|
||||
|
||||
Create a Pull Request with your changes. Please add any user-visible changes to
|
||||
`CHANGELOG.md`. The continuous integration build will run the tests and static
|
||||
analysis. It will also check that the pull request branch has no merge commits.
|
||||
When the changes are accepted, they will be merged or cherry-picked by an
|
||||
OpenTelemetry repository maintainers.
|
||||
This repository also includes [stylecop ruleset files](https://github.com/open-telemetry/opentelemetry-dotnet/tree/master/build). These files are used to configure the _StyleCop.Analyzers_ which runs during build. Breaking the rules will result in a build failure.
|
||||
|
|
|
|||
Loading…
Reference in New Issue