8000 docs: add instructions and details to contributors guide · cloudevents/sdk-javascript@3c870b5 · GitHub
[go: up one dir, main page]
Skip to content

Commit 3c870b5

Browse files
lancelance
committed
docs: add instructions and details to contributors guide
Signed-off-by: Lance Ball <lball@redhat.com>
1 parent c1fda94 commit 3c870b5

File tree

1 file changed

+203
-31
lines changed

1 file changed

+203
-31
lines changed

‎CONTRIBUTING.md

Lines changed: 203 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,190 @@
22

33
:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:
44

5-
Following you will see some guidelines about how to contribute with
6-
JavaScript SDK.
5+
We welcome contributions from the community! Please take some time to become
6+
acquainted with the process before submitting a pull request.
77

8-
## Branch Management
8+
## Pull Requests
9+
10+
When creating a pull request, first fork this repository and clone it to your
11+
local development environment. Then add this repository as the upstream.
912

10-
We use Gitflow to manage our branches and that's ok when `develop` branch is
11-
ahead of `master`.
13+
```console
14+
git clone https://github.com/mygithuborg/sdk-javascript.git
15+
cd sdk-javascript
16+
git remote add upstream https://github.com/cloudevents/sdk-javascript.git
17+
```
18+
19+
Typically a pull request should relate to an existing issue. If you have
20+
found a bug, want to add an improvement, or suggest an API change, please
21+
create an issue before proceeding with a pull request. For very minor changes
22+
such as typos in the documentation this isn't really necessary.
23+
24+
Create a branch for your work. If you are submitting a pull request that
25+
fixes or relates to an existing GitHub issue, you can use this in your
26+
branch name to keep things organized. For example, if you were to create
27+
a pull request to fix
28+
[this error with `httpAgent`](https://github.com/cloudevents/sdk-javascript/issues/48)
29+
you might create a branch named `48-fix-http-agent-error`.
30+
31+
```console
32+
git fetch upstream
33+
git reset --hard upstream/master
34+
git checkout -b 48-fix-http-agent-error
35+
```
1236

13-
- [Gitflow](https://nvie.com/posts/a-successful-git-branching-model/) by @nvie
37+
As you are working on your branch, changes may happen on `master`. Before
38+
submitting your pull request, be sure that your branch has been updated
39+
with the latest commits on `master`.
40+
41+
```console
42+
git rebase upstream/master
43+
```
44+
45+
This may cause conflicts if the files you are changing on your branch are
46+
also changed on master. Follow the `git` error messages to resolve these.
47+
If you've already pushed some changes to your `origin` fork, you'll
48+
need to force push these changes.
49+
50+
```console
51+
git push -f origin 48-fix-http-agent-error
52+
```
53+
54+
Once you have submitted your pull request, `master` may continue to evolve
55+
before your pull request has landed. If there are any commits on `master`
56+
that conflict with your changes, you may need to update your branch with
57+
these changes before the pull request can land.
58+
59+
```console
60+
git fetch upstream
61+
git rebase upstream/master
62+
# fix any potential conflicts
63+
git push -f origin 48-fix-http-agent-error
64+
```
65+
66+
This will cause the pull request to be updated with your changes, and
67+
CI will rerun.
68+
69+
### Updating Your Pull Request
70+
71+
A maintainer may ask you to make changes to your pull request. Sometimes these
72+
changes are minor and shouldn't appear in the commit log. For example, you may
73+
have a typo in one of your code comments that should be fixed before merge.
74+
You can prevent this from adding noise to the commit log with an interactive
75+
rebase. See the [git documentation](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
76+
for details.
77+
78+
```console
79+
git commit -m "fixup: fix typo"
80+
git rebase -i upstream/master # follow git instructions
81+
```
82+
83+
Once you have rebased your commits, you can force push to your fork as before.
84+
In most cases, there should only be a single commit in a pull request.
85+
86+
**NB: Be sure you have run all tests before submitting your pull request.**
87+
88+
### Commit Messages
89+
90+
Please follow the
91+
[Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/#summary).
92+
The first line of your commit should be prefixed with a type, be a single
93+
sentence with no period, and succinctly indicate what this commit changes.
94+
95+
All commit message lines should be kept to fewer than 80 characters if possible.
96+
97+
An example of a good commit message.
98+
99+
```log
100+
docs: remove 0.1, 0.2 spec support from README
101+
```
102+
103+
### Sign your work
104+
105+
Each PR must be signed. TLDR; use the `--signoff` flag for your commits.
106+
107+
```console
108+
git commit --signoff
109+
```
110+
111+
The sign-off is a signature line at the end of your commit message. Your
112+
signature certifies that you wrote the patch or otherwise have the right to pass
113+
it on as open-source code. The rules are pretty simple: if you can certify
114+
the below (from [developercertificate.org](http://developercertificate.org/)):
115+
116+
```
117+
Developer Certificate of Origin
118+
Version 1.1
119+
120+
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
121+
1 Letterman Drive
122+
Suite D4700
123+
San Francisco, CA, 94129
124+
125+
Everyone is permitted to copy and distribute verbatim copies of this
126+
license document, but changing it is not allowed.
127+
128+
Developer's Certificate of Origin 1.1
129+
130+
By making a contribution to this project, I certify that:
131+
132+
(a) The contribution was created in whole or in part by me and I
133+
have the right to submit it under the open source license
134+
indicated in the file; or
135+
136+
(b) The contribution is based upon previous work that, to the best
137+
of my knowledge, is covered under an appropriate open source
138+
license and I have the right under that license to submit that
139+
work with modifications, whether created in whole or in part
140+
by me, under the same open source license (unless I am
141+
permitted to submit under a different license), as indicated
142+
in the file; or
143+
144+
(c) The contribution was provided directly to me by some other
145+
person who certified (a), (b) or (c) and I have not modified
146+
it.
147+
148+
(d) I understand and agree that this project and the contribution
149+
are public and that a record of the contribution (including all
150+
personal information I submit with it, including my sign-off) is
151+
maintained indefinitely and may be redistributed consistent with
152+
this project or the open source license(s) involved.
153+
```
154+
155+
Then you just add a line to every git commit message:
156+
157+
Signed-off-by: Joe Smith <joe.smith@email.com>
158+
159+
Use your real name (sorry, no pseudonyms or anonymous contributions.)
160+
161+
If you set your `user.name` and `user.email` git configs, you can sign your
162+
commit automatically with `git commit -s`.
163+
164+
Note: If your git config information is set properly then viewing the `git log`
165+
information for your commit will look something like this:
166+
167+
```
168+
Author: Joe Smith <joe.smith@email.com>
169+
Date: Thu Feb 2 11:41:15 2018 -0800
170+
171+
Update README
172+
173+
Signed-off-by: Joe Smith <joe.smith@email.com>
174+
```
175+
176+
Notice the `Author` and `Signed-off-by` lines match. If they don't your PR will
177+
be rejected by the automated DCO check.
178+
179+
180+
## Style Guide
181+
182+
Code style for this module is maintained using [`eslint`](https://www.npmjs.com/package/eslint).
183+
When you run tests with `npm test` linting is performed first. If you want to
184+
check your code style for linting errors without running tests, you can just
185+
run `npm run lint`. If there are errors, you can usually fix them automatically
186+
by running `npm run fix`.
187+
188+
Linting rules are declared in [.eslintrc](https://github.com/cloudevents/sdk-javascript/blob/master/.eslintrc).
14189

15190
## Changelog
16191

@@ -29,34 +204,31 @@ fix: removed a bug that was causing the rotation of the earth to change
29204

30205
will show up in the "Bug Fixes" section of the changelog for a given release.
31206

32-
## Pull Requests
33-
34-
Guidelines about how to perform pull requests.
35-
36-
- before submit the PR, open an issue and link them
207+
## Maintainer's Guide
37208

38-
### Commit Messages
39-
40-
Please follow the Conventional Commits specification noted above. the first line of
41-
your commit should be prefixed with a type, be a single sentence with no period, and
42-
succinctly indicate what this commit changes.
43-
44-
All commit message lines should be kept to fewer than 80 characters if possible.
209+
Here are a few tips for repository maintainers.
45210

46-
### PR to `develop`
211+
* Stay on top of your pull requests. PRs that languish for too long can become difficult to merge.
212+
* Work from your own fork. As you are making contributions to the project, you should be working from your own fork just as outside contributors do. This keeps the branches in github to a minimum and reduces unnecessary CI runs.
213+
* Try to proactively label issues with backport labels if it's obvious that a change should be backported to previous releases.
214+
* When landing pull requests, if there is more than one commit, try to squash into a single commit. Usually this can just be done with the GitHub UI when merging the PR. Use "Squash and merge".
215+
* Triage issues once in a while in order to keep the repository alive. During the triage:
216+
* If some issues are stale for too long because they are no longer valid/relevant or because the discussion reached no significant action items to perform, close them and invite the users to reopen if they need it.
217+
* If some PRs are no longer valid but still needed, ask the user to rebase them
218+
* If some issues and PRs are still relevant, use labels to help organize tasks
219+
* If you find an issue that you want to create a fix for and submit a pull request, be sure to assign it to yourself so that others maintainers don't start working on it at the same time.
47220

48-
- fixes in the documentation (readme, contributors)
49-
- propose new files for the documentation
50-
- implementation of new features
51-
52-
### PR to `master`
53-
54-
- hot fixes
55-
56-
## Style Guide
221+
### Branch Management
57222

58-
_TODO_
223+
The `master` branch is is the bleeding edge. New major versions of the module
224+
are cut from this branch and tagged. If you intend to submit a pull request
225+
you should use `master HEAD` as your starting point.
59226

60-
### JavaScript Style Guide
227+
Each major release will result in a new branch and tag. For example, the
228+
release of version 1.0.0 of the module will result in a `v1.0.0` tag on the
229+
release commit, and a new branch `v1.x.y` for subsequent minor and patch
230+
level releases of that major version. However, development will continue
231+
apace on `master` for the next major version - e.g. 2.0.0. Version branches
232+
are only created for each major version. Minor and patch level releases
233+
are simply tagged.
61234

62-
_TODO_

0 commit comments

Comments
 (0)
0