docs: add instructions and details to contributors guide

Signed-off-by: Lance Ball <[email protected]>

Author: lance

CONTRIBUTING.md

@@ -2,38 +2,87 @@
 
 :+1::tada: First off, thanks for taking the time to contribute! :tada::+1:
 
-Following you will see some guidelines about how to contribute with
-JavaScript SDK.
+We welcome contributions from the community! Please take some time to become
+acquainted with the process before submitting a pull request.
 
-## Branch Management
+## Pull Requests
 
-We use Gitflow to manage our branches and that's ok when `develop` branch is
-ahead of `master`.
+When creating a pull request, first fork this repository and clone it to your
+local development environment. Then add this repository as the upstream.
 
-- [Gitflow](https://nvie.com/posts/a-successful-git-branching-model/) by @nvie
+```console
+git clone https://github.com/mygithuborg/sdk-javascript.git
+git remote add upstream https://github.com/cloudevents/sdk-javascript.git
+```
 
-## Changelog
+Typically a pull request should relate to an existing issue. 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. For very minor changes
+such as typos in the documentation this isn't really necessary.
+
+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/master
+git co -b 48-fix-http-agent-error
+```
 
-The [CHANGELOG.md](./CHANGELOG.md) will be updated with your commits if you format
-your commit messages following the
-[Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/#summary).
-If you are unsure what prefix to use for a commit, you can consult the
-[package.json](https://github.com/cloudevents/sdk-javascript/blob/master/package.json) file
-in this repository. 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:
+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 on `master`.
 
-```log
-fix: removed a bug that was causing the rotation of the earth to change
+```console
+git rebase upstream/master
 ```
 
-will show up in the "Bug Fixes" section of the changelog for a given release.
+This may cause conflicts if the files you are changing on your branch are
+also changed on master. Follow the `git` error messages to resolve these.
+If you've already pushed some changes to your `origin` fork, you'll
+need to force push these changes.
 
-## Pull Requests
+```console
+git push -f origin 48-fix-http-agent-error
+```
+
+Once you have submitted 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.
+
+```console
+git fetch upstream
+git rebase upstream/master
+# 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.
+
+### Updating Your Pull Request
+
+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
+```
 
-Guidelines about how to perform pull requests.
+Once you have rebased your commits, you can force push to your fork as before.
+In most cases, there should only be a single commit in a pull request.
 
-- before submit the PR, open an issue and link them
+**NB: Be sure you have run all tests before submitting your pull request.**
 
 ### Commit Messages
 
@@ -43,20 +92,66 @@ succinctly indicate what this commit changes.
 
 All commit message lines should be kept to fewer than 80 characters if possible.
 
-### PR to `develop`
+## Style Guide
 
-- fixes in the documentation (readme, contributors)
-- propose new files for the documentation
-- implementation of new features
+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`.
 
-### PR to `master`
+Linting rules are declared in [.eslintrc](https://github.com/cloudevents/sdk-javascript/blob/master/.eslintrc).
 
-- hot fixes
 
-## Style Guide
+## Branch Management
+
+The `master` branch is is the bleeding edge. New major versions of the module
+are cut from this branch and tagged. If you intend to submit a pull request
+you should use `master HEAD` as your starting point.
+
+Each major release will result in a new branch and tag. For example, the
+release of version 1.0.0 of the module will result in a `v1.0.0` tag on the
+release commit, and a new branch `v1.x.y` for subsequent minor and patch
+level releases of that major version. However, development will continue
+apace on `master` for the next major version - e.g. 2.0.0. Version branches
+are only created for each major version. Minor and patch level releases
+are simply tagged on the major version branch.
+
+If there is a change on `master` that should be backported to a previous version,
+the pull request for that change should be labeled with the `v1.x.y-backport`
+label. When it comes time to release a minor or patch level version of a
+previous release, the commits in these labeled pull requests will be cherry
+picked and backported to the `v1.x.y` branch, for example, and a new tag is
+applied, e.g. `v1.1.0`.
+
+** NB Most of these tasks are handled by maintainers. Community contributors
+will typically not need to worry about all of this. **
+
+## Changelog
+
+The [CHANGELOG.md](./CHANGELOG.md) will be updated with your commits if you format
+your commit messages following the
+[Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/#summary).
+If you are unsure what prefix to use for a commit, you can consult the
+[package.json](https://github.com/cloudevents/sdk-javascript/blob/master/package.json) file
+in this repository. 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.
 
-_TODO_
+## Maintainer's Guide
 
-### JavaScript Style Guide
+Here are a few tips for repository maintainers.
 
-_TODO_
+* Stay on top of your pull requests. PRs that languish for too long can become
+difficult to merge.
+* 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.
+* Try to proactively label issues with backport labels if it's obvious that a
+change should be backported to previous releases.