Skip to content

Commit 1d077d4

Browse files
jskeetjskeet
committed
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 <[email protected]>
1 parent b1f29cf commit 1d077d4

File tree

2 files changed

+168
-0
lines changed

2 files changed

+168
-0
lines changed

‎CONTRIBUTING.md

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Contributing to CloudEvents C# SDK
2+
3+
We welcome contributions from the community! Please take some time to become
4+
acquainted with the process before submitting a pull request. There are just
5+
a few things to keep in mind.
6+
7+
# Issues
8+
9+
If you have found a bug, want to add an improvement, or suggest an
10+
API change, please create an issue before proceeding with a pull
11+
request. If you are intending to create a pull request yourself,
12+
please indicate this in the issue to avoid duplication of work.
13+
14+
Please be aware that while the maintainers are typically familiar
15+
with the core aspects of CloudEvents, along with the HTTP transport
16+
options, and JSON/XML/Protobuf event formats, they are less
17+
experienced with some other transports and formats (such as AMQP and
18+
Kafka). If you have a feature request or issue around these, you may
19+
need to provide more details or even implement the improvement
20+
yourself - with support from the maintainers, of course.
21+
22+
# Pull requests
23+
24+
Typically, a pull request should relate to an existing issue. For
25+
very minor changes such as typos in the documentation this isn't
26+
really necessary.
27+
28+
## Getting started
29+
30+
When creating a pull request, first fork this repository and clone it to your
31+
local development environment. Then add this repository as the upstream.
32+
33+
```console
34+
git clone https://github.com/mygithuborg/sdk-csharp.git
35+
cd sdk-csharp
36+
git remote add upstream https://github.com/cloudevents/sdk-csharp.git
37+
```
38+
39+
## Branches
40+
41+
The first thing you'll need to do is create a branch for your work.
42+
If you are submitting a pull request that fixes or relates to an existing
43+
GitHub issue, you can use the issue number in your branch name to keep things
44+
organized.
45+
46+
```console
47+
git fetch upstream
48+
git reset --hard upstream/master
49+
git checkout master
50+
git checkout -b fix-some-issue
51+
```
52+
53+
## Commit Messages
54+
55+
All commit message lines should be kept to fewer than 80 characters if possible.
56+
57+
Commit messages following [Conventional Commits]
58+
(https://www.conventionalcommits.org/en/v1.0.0/#summary) are
59+
welcome, but not currently required.
60+
61+
Where the commit addresses an issue, please refer to that
62+
numerically. For example:
63+
64+
```log
65+
fix: Make HTTP header handling case-insensitive
66+
67+
Fixes #12345
68+
```
69+
70+
### Signing your commits
71+
72+
Each commit must be signed. Use the `--signoff` flag for your commits.
73+
74+
```console
75+
git commit --signoff
76+
```
77+
78+
This will add a line to every git commit message:
79+
80+
Signed-off-by: Joe Smith <[email protected]>
81+
82+
Use your real name (sorry, no pseudonyms or anonymous contributions.)
83+
84+
The sign-off is a signature line at the end of your commit message. Your
85+
signature certifies that you wrote the patch or otherwise have the right to pass
86+
it on as open-source code. See [developercertificate.org](http://developercertificate.org/)
87+
for the full text of the certification.
88+
89+
Be sure to have your `user.name` and `user.email` set in your git config.
90+
If your git config information is set properly then viewing the `git log`
91+
information for your commit will look something like this:
92+
93+
```
94+
Author: Joe Smith <[email protected]>
95+
Date: Thu Feb 2 11:41:15 2018 -0800
96+
97+
Update README
98+
99+
Signed-off-by: Joe Smith <[email protected]>
100+
```
101+
102+
Notice the `Author` and `Signed-off-by` lines match. If they don't your PR will
103+
be rejected by the automated DCO check.
104+
105+
## Staying Current with `master`
106+
107+
As you are working on your branch, changes may happen on `master`. Before
108+
submitting your pull request, be sure that your branch has been updated
109+
with the latest commits.
110+
111+
```console
112+
git fetch upstream
113+
git rebase upstream/master
114+
```
115+
116+
This may cause conflicts if the files you are changing on your branch are
117+
also changed on master. Error messages from `git` will indicate if conflicts
118+
exist and what files need attention. Resolve the conflicts in each file, then
119+
continue with the rebase with `git rebase --continue`.
120+
121+
122+
If you've already pushed some changes to your `origin` fork, you'll
123+
need to force push these changes.
124+
125+
```console
126+
git push -f origin fix-some-issue
127+
```
128+
129+
## Submitting and updating your pull request
130+
131+
Before submitting a pull request, you should make sure that all of the tests
132+
successfully pass.
133+
134+
Once you have sent your pull request, `master` may continue to evolve
135+
before your pull request has landed. If there are any commits on `master`
136+
that conflict with your changes, you may need to update your branch with
137+
these changes before the pull request can land. Resolve conflicts the same
138+
way as before.
139+
140+
```console
141+
git fetch upstream
142+
git rebase upstream/master
143+
# fix any potential conflicts
144+
git push -f origin fix-some-issue
145+
```
146+
147+
This will cause the pull request to be updated with your changes, and
148+
CI will rerun.
149+
150+
A maintainer may ask you to make changes to your pull request. Sometimes these
151+
changes are minor and shouldn't appear in the commit log. For example, you may
152+
have a typo in one of your code comments that should be fixed before merge.
153+
You can prevent this from adding noise to the commit log with an interactive
154+
rebase. See the [git documentation](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
155+
for details.
156+
157+
```console
158+
git commit -m "fixup: fix typo"
159+
git rebase -i upstream/master # follow git instructions
160+
```
161+
162+
Once you have rebased your commits, you can force push to your fork as before.

‎MAINTAINERS.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Maintainers
2+
3+
Current active maintainers of this SDK:
4+
5+
- [Jon Skeet](https://github.com/jskeet)
6+
- [Josh Love](https://github.com/JoshLove-msft)

0 commit comments

Comments
 (0)