Skip to content

Latest commit

 

History

History
41 lines (38 loc) · 3.16 KB

CONTRIBUTING.md

File metadata and controls

41 lines (38 loc) · 3.16 KB

Guidelines

  • Modules must not depend on any other npm modules (including other just modules)
  • Always assume Just modules will be used in hot code and code accordingly
    • Write in ES5 when possible. If you have to support user argument which have ES5+ types (e.g. Set and Map) you may upgrade to newer syntax (within our stated platform support levels) but please bump the major version to protect legacy users.
    • Favor for loops over high order functions
    • Don't repeatedly access the same property, assign it to a var
  • Brevity
    • A lot of people choose Just utilities to minimize their app's JS footprint in memory/network constrained environments
    • Keep it brief and don't add redundant code. Most utilities should fit into one shortish function.
  • API
    • Keep the API simple and intuitive
    • Avoid multiple arguments or option arguments whenever possible–-make it just do one thing
  • Tests
    • Write a test for every use case
    • At a minimum, include tests for each example you included in the README
    • Be sure to also test for cases that should throw exceptions
    • Too thorough is better than not thorough enough
  • TypeScript
    • We're in the process of adding typescript definitions (index.d.ts) and tests (index.tests.ts) for every utility
    • Please add these files for your new utility if you feel comfortable doing so. Here's an example PR.
    • Also add "types": "index.d.ts" after main entry in package.json.
    • You can verify new TypeScript definitions by running yarn test-types (This also gets run as part of the yarn test script)
  • Publishing the module and Interactive gh-pages (http://anguscroll.com/just)
    • We'll take care of both of these after we land your PR.

README template

  • Thanks to Max Synnott, local and global READMEs are now autogenerated from a template.
  • Add a new section to md-variables.com for your package:
    • root key: the name value from your package.json (e.g. just-compact)
    • packageName: same as root key
    • dir: the directory you wrote your package in (e.g. array-compact)
    • description: a one sentence description of what the utility does (for line breaks use an array of strings)
    • examples: a comprehensive array of example code showing how to use the package
      • try to add examples for mainstream cases and some edge cases
      • start with an element for the import statement, followed by an empty string element
      • follow up with usage examples, one element per example
  • Finally run yarn generate-readmes or npm run generate-readmes to update all READMEs with your changes.

App Testing

Raul Melo has written a nice test framework for testing cjs and esm imports of Just utilities in a variety of common app environments. Take advantage of this if you want to test how a module will work in the context of a given app.