180 lines
6.2 KiB
Markdown
180 lines
6.2 KiB
Markdown
# Pull Request Guidelines
|
|
|
|
Here you will find step by step guidance for creating, submitting and updating
|
|
a pull request in this repository. We hope it will help you have an easy time
|
|
managing your work and a positive, satisfying experience when contributing
|
|
your code. Thanks for getting involved! :rocket:
|
|
|
|
- [Pull Request Guidelines](#pull-request-guidelines)
|
|
- [Getting Started](#getting-started)
|
|
- [Branches](#branches)
|
|
- [Commit Messages](#commit-messages)
|
|
- [Signing your commits](#signing-your-commits)
|
|
- [Staying Current with `main`](#staying-current-with-main)
|
|
- [Style Guide](#style-guide)
|
|
- [Submitting and Updating Your Pull Request](#submitting-and-updating-your-pull-request)
|
|
- [Congratulations!](#congratulations)
|
|
|
|
## 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-javascript.git
|
|
cd sdk-javascript
|
|
git remote add upstream https://github.com/cloudevents/sdk-javascript.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 this in your branch name to keep things organized.
|
|
For example, if you were to create a pull request to fix
|
|
[this error with `httpAgent`](https://github.com/cloudevents/sdk-javascript/issues/48)
|
|
you might create a branch named `48-fix-http-agent-error`.
|
|
|
|
```console
|
|
git fetch upstream
|
|
git reset --hard upstream/main
|
|
git checkout FETCH_HEAD
|
|
git checkout -b 48-fix-http-agent-error
|
|
```
|
|
|
|
## Commit Messages
|
|
|
|
Please follow the
|
|
[Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/#summary).
|
|
The first line of your commit should be prefixed with a type, be a single
|
|
sentence with no period, and succinctly indicate what this commit changes.
|
|
|
|
All commit message lines should be kept to fewer than 80 characters if possible.
|
|
|
|
An example of a good commit message.
|
|
|
|
```log
|
|
docs: remove 0.1, 0.2 spec support from README
|
|
```
|
|
|
|
If you are unsure what prefix to use for a commit, you can consult the
|
|
[package.json](package.json) file.
|
|
In the `standard-version.types` section, you can see all of the commit
|
|
types that will be committed to the changelog based on the prefix in the first line of
|
|
your commit message. For example, the commit message:
|
|
|
|
```log
|
|
fix: removed a bug that was causing the rotation of the earth to change
|
|
```
|
|
|
|
will show up in the "Bug Fixes" section of the changelog for a given release.
|
|
|
|
### 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 `main`
|
|
|
|
As you are working on your branch, changes may happen on `main`. Before
|
|
submitting your pull request, be sure that your branch has been updated
|
|
with the latest commits.
|
|
|
|
```console
|
|
git fetch upstream
|
|
git rebase upstream/main
|
|
```
|
|
|
|
This may cause conflicts if the files you are changing on your branch are
|
|
also changed on main. 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 48-fix-http-agent-error
|
|
```
|
|
|
|
## Style Guide
|
|
|
|
Code style for this module is maintained using [`eslint`](https://www.npmjs.com/package/eslint).
|
|
When you run tests with `npm test` linting is performed first. If you want to
|
|
check your code style for linting errors without running tests, you can just
|
|
run `npm run lint`. If there are errors, you can usually fix them automatically
|
|
by running `npm run fix`.
|
|
|
|
Linting rules are declared in [.eslintrc](https://github.com/cloudevents/sdk-javascript/blob/main/.eslintrc).
|
|
|
|
## Submitting and Updating Your Pull Request
|
|
|
|
Before submitting a pull request, you should make sure that all of the tests
|
|
successfully pass by running `npm test`.
|
|
|
|
Once you have sent your pull request, `main` may continue to evolve
|
|
before your pull request has landed. If there are any commits on `main`
|
|
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/main
|
|
# fix any potential conflicts
|
|
git push -f origin 48-fix-http-agent-error
|
|
```
|
|
|
|
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/main # follow git instructions
|
|
```
|
|
|
|
Once you have rebased your commits, you can force push to your fork as before.
|
|
|
|
## Congratulations!
|
|
|
|
Congratulations! You've done it! We really appreciate the time and energy
|
|
you've given to the project. Thank you.
|