docs: Initial docs for contributing and the maintainer list
The contribution guide is largely copied from https://github.com/cloudevents/sdk-java/blob/master/CONTRIBUTING.md with suitable changes. Fixes #204 Signed-off-by: Jon Skeet <jonskeet@google.com>
This commit is contained in:
parent
b1f29cf25b
commit
1d077d4e57
|
@ -0,0 +1,162 @@
|
||||||
|
# Contributing to CloudEvents C# SDK
|
||||||
|
|
||||||
|
We welcome contributions from the community! Please take some time to become
|
||||||
|
acquainted with the process before submitting a pull request. There are just
|
||||||
|
a few things to keep in mind.
|
||||||
|
|
||||||
|
# Issues
|
||||||
|
|
||||||
|
If you have found a bug, want to add an improvement, or suggest an
|
||||||
|
API change, please create an issue before proceeding with a pull
|
||||||
|
request. If you are intending to create a pull request yourself,
|
||||||
|
please indicate this in the issue to avoid duplication of work.
|
||||||
|
|
||||||
|
Please be aware that while the maintainers are typically familiar
|
||||||
|
with the core aspects of CloudEvents, along with the HTTP transport
|
||||||
|
options, and JSON/XML/Protobuf event formats, they are less
|
||||||
|
experienced with some other transports and formats (such as AMQP and
|
||||||
|
Kafka). If you have a feature request or issue around these, you may
|
||||||
|
need to provide more details or even implement the improvement
|
||||||
|
yourself - with support from the maintainers, of course.
|
||||||
|
|
||||||
|
# Pull requests
|
||||||
|
|
||||||
|
Typically, a pull request should relate to an existing issue. For
|
||||||
|
very minor changes such as typos in the documentation this isn't
|
||||||
|
really necessary.
|
||||||
|
|
||||||
|
## Getting started
|
||||||
|
|
||||||
|
When creating a pull request, first fork this repository and clone it to your
|
||||||
|
local development environment. Then add this repository as the upstream.
|
||||||
|
|
||||||
|
```console
|
||||||
|
git clone https://github.com/mygithuborg/sdk-csharp.git
|
||||||
|
cd sdk-csharp
|
||||||
|
git remote add upstream https://github.com/cloudevents/sdk-csharp.git
|
||||||
|
```
|
||||||
|
|
||||||
|
## Branches
|
||||||
|
|
||||||
|
The first thing you'll need to do is create a branch for your work.
|
||||||
|
If you are submitting a pull request that fixes or relates to an existing
|
||||||
|
GitHub issue, you can use the issue number in your branch name to keep things
|
||||||
|
organized.
|
||||||
|
|
||||||
|
```console
|
||||||
|
git fetch upstream
|
||||||
|
git reset --hard upstream/master
|
||||||
|
git checkout master
|
||||||
|
git checkout -b fix-some-issue
|
||||||
|
```
|
||||||
|
|
||||||
|
## Commit Messages
|
||||||
|
|
||||||
|
All commit message lines should be kept to fewer than 80 characters if possible.
|
||||||
|
|
||||||
|
Commit messages following [Conventional Commits]
|
||||||
|
(https://www.conventionalcommits.org/en/v1.0.0/#summary) are
|
||||||
|
welcome, but not currently required.
|
||||||
|
|
||||||
|
Where the commit addresses an issue, please refer to that
|
||||||
|
numerically. For example:
|
||||||
|
|
||||||
|
```log
|
||||||
|
fix: Make HTTP header handling case-insensitive
|
||||||
|
|
||||||
|
Fixes #12345
|
||||||
|
```
|
||||||
|
|
||||||
|
### Signing your commits
|
||||||
|
|
||||||
|
Each commit must be signed. Use the `--signoff` flag for your commits.
|
||||||
|
|
||||||
|
```console
|
||||||
|
git commit --signoff
|
||||||
|
```
|
||||||
|
|
||||||
|
This will add a line to every git commit message:
|
||||||
|
|
||||||
|
Signed-off-by: Joe Smith <joe.smith@email.com>
|
||||||
|
|
||||||
|
Use your real name (sorry, no pseudonyms or anonymous contributions.)
|
||||||
|
|
||||||
|
The sign-off is a signature line at the end of your commit message. Your
|
||||||
|
signature certifies that you wrote the patch or otherwise have the right to pass
|
||||||
|
it on as open-source code. See [developercertificate.org](http://developercertificate.org/)
|
||||||
|
for the full text of the certification.
|
||||||
|
|
||||||
|
Be sure to have your `user.name` and `user.email` set in your git config.
|
||||||
|
If your git config information is set properly then viewing the `git log`
|
||||||
|
information for your commit will look something like this:
|
||||||
|
|
||||||
|
```
|
||||||
|
Author: Joe Smith <joe.smith@email.com>
|
||||||
|
Date: Thu Feb 2 11:41:15 2018 -0800
|
||||||
|
|
||||||
|
Update README
|
||||||
|
|
||||||
|
Signed-off-by: Joe Smith <joe.smith@email.com>
|
||||||
|
```
|
||||||
|
|
||||||
|
Notice the `Author` and `Signed-off-by` lines match. If they don't your PR will
|
||||||
|
be rejected by the automated DCO check.
|
||||||
|
|
||||||
|
## Staying Current with `master`
|
||||||
|
|
||||||
|
As you are working on your branch, changes may happen on `master`. Before
|
||||||
|
submitting your pull request, be sure that your branch has been updated
|
||||||
|
with the latest commits.
|
||||||
|
|
||||||
|
```console
|
||||||
|
git fetch upstream
|
||||||
|
git rebase upstream/master
|
||||||
|
```
|
||||||
|
|
||||||
|
This may cause conflicts if the files you are changing on your branch are
|
||||||
|
also changed on master. Error messages from `git` will indicate if conflicts
|
||||||
|
exist and what files need attention. Resolve the conflicts in each file, then
|
||||||
|
continue with the rebase with `git rebase --continue`.
|
||||||
|
|
||||||
|
|
||||||
|
If you've already pushed some changes to your `origin` fork, you'll
|
||||||
|
need to force push these changes.
|
||||||
|
|
||||||
|
```console
|
||||||
|
git push -f origin fix-some-issue
|
||||||
|
```
|
||||||
|
|
||||||
|
## Submitting and updating your pull request
|
||||||
|
|
||||||
|
Before submitting a pull request, you should make sure that all of the tests
|
||||||
|
successfully pass.
|
||||||
|
|
||||||
|
Once you have sent your pull request, `master` may continue to evolve
|
||||||
|
before your pull request has landed. If there are any commits on `master`
|
||||||
|
that conflict with your changes, you may need to update your branch with
|
||||||
|
these changes before the pull request can land. Resolve conflicts the same
|
||||||
|
way as before.
|
||||||
|
|
||||||
|
```console
|
||||||
|
git fetch upstream
|
||||||
|
git rebase upstream/master
|
||||||
|
# fix any potential conflicts
|
||||||
|
git push -f origin fix-some-issue
|
||||||
|
```
|
||||||
|
|
||||||
|
This will cause the pull request to be updated with your changes, and
|
||||||
|
CI will rerun.
|
||||||
|
|
||||||
|
A maintainer may ask you to make changes to your pull request. Sometimes these
|
||||||
|
changes are minor and shouldn't appear in the commit log. For example, you may
|
||||||
|
have a typo in one of your code comments that should be fixed before merge.
|
||||||
|
You can prevent this from adding noise to the commit log with an interactive
|
||||||
|
rebase. See the [git documentation](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
|
||||||
|
for details.
|
||||||
|
|
||||||
|
```console
|
||||||
|
git commit -m "fixup: fix typo"
|
||||||
|
git rebase -i upstream/master # follow git instructions
|
||||||
|
```
|
||||||
|
|
||||||
|
Once you have rebased your commits, you can force push to your fork as before.
|
|
@ -0,0 +1,6 @@
|
||||||
|
# Maintainers
|
||||||
|
|
||||||
|
Current active maintainers of this SDK:
|
||||||
|
|
||||||
|
- [Jon Skeet](https://github.com/jskeet)
|
||||||
|
- [Josh Love](https://github.com/JoshLove-msft)
|
Loading…
Reference in New Issue