Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
141 lines (94 loc) · 7.14 KB

CONTRIBUTING.md

File metadata and controls

141 lines (94 loc) · 7.14 KB

Contributor guidelines

Thinking about contributing to RES? Awesome! We just ask that you follow a few simple guidelines:

  1. RES has grown quite large, so we have carefully choose what features we should add to avoid maintenance burden and code bloat. If you're unsure if your feature would appeal to a wide audience, please post about it on /r/Enhancement.

  2. There are a few features we have made a conscious choice not to add to RES, so make sure whatever you'd like to contribute isn't on that list.

  3. To build the extension, see Building development versions of the extension.

  4. To add new modules or hosts, see Adding new files.

  5. To check code style and autofix some formatting errors, see Lint and test commands.

Building development versions of the extension

First time installation

  1. Install git.
  2. Install node.js (version >= 6).
  3. Install Python 2 (not version 3). On Windows, please install the "Add python.exe to path" feature on the customize screen.
  4. Clone this repository.
  5. Run npm install in that folder.

Once done, you can build the extension by running npm start (see Build commands).

To load the extension into your browser, see Loading RES into your browser.

Build commands

npm start [-- <browsers>] will clean dist/, then build RES (dev mode), and start a watch task that will rebuild RES when you make changes. Only changed files will be rebuilt.

npm run once [-- <browsers>] will clean dist/, then build RES (dev mode) a single time.

npm run build [-- <browsers>] will clean dist/, then build RES (release mode). Each build output will be compressed to a .zip file in dist/zip/.

<browsers> is a comma-separated list of browsers to target, e.g. chrome,firefox,edge. all will build all targets. By default, chrome will be targeted.

Lint and test commands

npm run lint will verify the code style (and point out any errors) of all .js files in lib/ (except lib/vendor/) using ESLint, as well as all .scss files with sass-lint.

npm run lint-fix will autofix any fixable lint issues.

npm run flow will run Flow type checking, and start the Flow server so future runs will complete faster. Use npm run flow -- stop to stop the server, or npm run flow -- check to run Flow once without starting the server.

npm test will run unit tests (in __tests__ directories) using Ava.

npm run integration -- <browsers> will run integration tests (in tests/) using Nightwatch.js. Currently just chrome and firefox can be targeted.

To run integration tests locally, you need to run an instance of Selenium Standalone Server and have either ChromeDriver or GeckoDriver on your PATH. The selenium-standalone package may help with this. The default host and port (localhost and 4444) should work for most local installations, but if necessary they can be overridden with the SELENIUM_HOST and SELENIUM_PORT environment variables.

Loading RES into your browser

Chrome
  1. Go to Menu->Tools->Extensions and tick the Developer Mode checkbox.
  2. Click Load unpacked extension and select the /dist/chrome folder (not the /chrome folder).
  3. Any time you make changes, you must go back to the Menu->Tools->Extensions page and Reload the extension.
Microsoft Edge
  1. Go to about:flags and tick the Enable extension developer features checkbox.
  2. Click Load extension on the extensions menu and select the /dist/edgeextension/manifest/Extension folder (not the /edge folder).
  3. Any time you make changes, you must go back to the Menu->Extensions page, go to the extension's settings and Reload the extension.
Firefox
  1. Go to about:debugging and tick the Enable add-on debugging checkbox.
  2. Click Load Temporary Add-on and select /dist/firefox/manifest.json (not the /firefox folder).
  3. Any time you make changes, you must go back to the about:debugging page and Reload the extension.

Project structure

Top level files and folders

  • .github/: Github templates
  • browser/: extension API files common to all browsers
  • build/: files handling automated browser deployments
  • changelog/: release changelogs
  • chrome/: Chrome-specific RES files
  • dist/: build output
  • edge/: Microsoft Edge-specific RES files
  • examples/: example code for new hosts/modules
  • firefox/: Firefox-specific RES files
  • images/: images for RES logo and CSS icons
  • lib/: all RES code
  • lib/core/: core RES code
  • lib/css/: RES css
  • lib/environment/: RES environment code
  • lib/images/: RES images
  • lib/modules/: RES modules
  • lib/templates/: RES templates
  • lib/utils/: RES utilities
  • lib/vendor/: RES vendor libraries (old libs not on npm)
  • lib/**/__tests__: unit tests
  • locales: RES i18n translations
  • tests/: integration tests
  • package.json: package info, dependencies
  • webpack.config.babel.js: build script

Adding new files

Modules

First, check to see if there is an existing module with the same focus.

See examples/module.js for an example.

Create a new .js file in lib/modules. It will automatically be loaded when the build script is restarted.

All user-visible text must be translated. See the locales README for details.

Media hosts

See examples/host.js for an example.

Create a new .js file in lib/modules/hosts. It will automatically be loaded when the build script is restarted.

If the host uses an API that does not support CORS, you must add it to the browsers' manifests and the host's permissions property. For example, search for usages of api.twitter.com.

Stylesheets

Create a new .scss file in lib/css/modules/ (with a leading underscore, e.g. _myModule.scss). Import the file in lib/css/res.scss (e.g. @import 'modules/myPartial';).

For toggleable CSS, add bodyClass: true to an option or module, then wrap your CSS with .res-moduleId-optionKey (boolean options), .res-moduleId-optionKey-optionValue (enum options), or .res-moduleId (modules).

For example:

.res-showImages-hideImages {
	img {
		display: none;
	}
}