Skip to content

Latest commit

 

History

History
197 lines (145 loc) · 7.15 KB

CONTRIBUTING.md

File metadata and controls

197 lines (145 loc) · 7.15 KB
Raw

Contributing

Thanks for stopping by. If you’re here because you’re considering contributing then 🎉 ! This document should have you covered for most things, but if you have any questions give us a shout (@bengourley is the current lead maintainer, feel free to ping him on Twitter).

How to contribute

Reporting issues

If you think you've spotted a problem with this module, feel free to open up a new issue. There are a couple of things you should check before doing so:

  • Do you have the latest version of bugsnag-js? If not, does updating to the latest version fix your issue?
  • Has somebody else already reported your issue? Feel free to comment or check-in on an existing issue that matches your own.
  • Is your problem definitely to do with this module? Only things related to the JavaScript notifier should be reported here. For anything else, email [email protected].

Fixing issues

If you've identified a fix to a new or existing issue, we welcome contributions!

Adding features

In general, feature additions will come from Bugsnag employees. If you think you have a useful addition that doesn’t take long to create a pull request for, feel free to go ahead and make it and strike up a discussion. With any non-trivial amount of work, the best thing to do is create an issue in which to discuss the feature, for the following reasons:

  • Bugsnag has an internal roadmap of things to work on. We might have already planned to work on your suggested feature.
  • We might disagree about whether the addition is worthwhile or not.
  • We might agree that the addition is worthwhile but disagree with the implementation.

That said, we have had some tremendous contributions from the community in the past, so use your best judgement. What we want to avoid here is anybody feeling like they’ve wasted their time!

System requirements

In order to develop on the project you’ll need to be on Mac/Linux٭. All you’ll need is:

[٭] if you’re on Windows and want to contribute, we’d welcome help making the development experience cross-platform

QA

tl;dr: any changes must come with tests and must lint successfully.

Testing

Unit tests

Every file in base should be 100% covered by unit tests. These tests can run in Node (not every browser). This means they are fast. They serve the purpose of validating that the logic is sound, and that individual components are implemented correctly, functioning as intended. They do not provide guarantees for any other environments.

Command

npm run test:unit

Integration tests

The entire module (and any publicly-exported subcomponents) should be tested against all of the environments we support. Each high-level feature and distinct configuration should be run. 100% coverage is the aim, but different environments will take different code paths so coverage reporting is tricky. Code Climate aggregates coverage reports from each browser which helps us detect totally uncovered lines.

Command

npm run test:integration
npm run test:integration:quick # runs only in headless Chrome for quicker results

End-to-end tests

The entire module should be included via all of the supported delivery mechanisms (<script>, require(…), AMD etc.) in real environments. Not every permutation and configuration option needs to be tested at this level. Too many tests here make for a brittle suite that will be a maintenance overhead, so we need to strike a balance.

Command

npm run test:e2e
npm run test:e2e:quick # runs only in headless Chrome for quicker results

Linting

JavaScript source files are written in standard style. The TypeScript definition files are linted with tslint. You should configure your editor to lint while you code as it's best to catch errors early.

Command

npm run lint

Releases

Ensure you have the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables set. Also ensure 2FA is enabled on your AWS account.

Releases are automated as much as possible and abstracted into the following commands…

Prerelease

npm version pre{patch|minor|major}

It is usually best to do a prerelease before a full release. The prerelease command will do the following:

  • Increment the version number
  • Ensure the unit tests and linter pass
  • Update the table of contents CONTRIBUTING.md
  • Update the size badge in the README.md
  • Update version in package.json
  • Create the build assets in dist/
  • Create a version commit (e.g. 4.0.0-3) and tag (e.g. v4.0.0-3)
  • Push commits and tags
  • Publish to npm with the tag unstable
  • Upload built assets to the CDN

If you are incrementing on a version that is already prerelease you can just supply pre as the argument which will increment the prerelease component of the version number.

Release

When you are happy with the prerelease, you can release it with the following command:

npm version {patch|minor|major}

The release command will do the following:

  • Increment the version number
  • Ensure the unit tests and linter pass
  • Update the table of contents CONTRIBUTING.md
  • Update the size badge in the README.md
  • Update version in package.json
  • Prompt for a changelog entry and insert it into CHANGELOG.md
  • Create the build assets in dist/
  • Create a version commit (e.g. 4.0.0) and tag (e.g. v4.0.0)
  • Push commits and tags
  • Publish to npm with the tag latest
  • Upload built assets to the CDN

This command will launch your into your $EDITOR and get you to create a changelog entry for the release (much like git commit does). Tailor the contents to the specifics of the release you are creating, then save and exit. The contents of the file you edit will be formatted and inserted into CHANGELOG.md.