docs: add instructions and details to contributors guide

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

Author: lance

CONTRIBUTING.md

@@ -2,61 +2,160 @@
 
 :+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
+cd sdk-javascript
+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 checkout -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
+```
 
-Guidelines about how to perform pull requests.
+This will cause the pull request to be updated with your changes, and
+CI will rerun.
 
-- before submit the PR, open an issue and link them
+### 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
+```
+
+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.
+
+**NB: Be sure you have run all tests before submitting your pull request.**
 
 ### Commit Messages
 
-Please follow the Conventional Commits specification noted above. 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.
+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.
 
-### PR to `develop`
+An example of a good commit message.
 
-- fixes in the documentation (readme, contributors)
-- propose new files for the documentation
-- implementation of new features
+```log
+docs: remove 0.1, 0.2 spec support from README
+```
 
-### PR to `master`
+## Style Guide
 
-- hot fixes
+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`.
 
-## Style Guide
+Linting rules are declared in [.eslintrc](https://github.com/cloudevents/sdk-javascript/blob/master/.eslintrc).
+
+## 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.
+* When landing pull requests, if there is more than one commit, try to squash into a single commit.