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:
Jon Skeet 2022-04-05 09:56:08 +01:00 committed by Jon Skeet
parent b1f29cf25b
commit 1d077d4e57
2 changed files with 168 additions and 0 deletions

162
CONTRIBUTING.md Normal file
View File

@ -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.

6
MAINTAINERS.md Normal file
View File

@ -0,0 +1,6 @@
# Maintainers
Current active maintainers of this SDK:
- [Jon Skeet](https://github.com/jskeet)
- [Josh Love](https://github.com/JoshLove-msft)