Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Create CONTRIBUTING.md * move contributing info to CONTRIBUTING.md so GitHub will link it when opening a PR * make "Contributor guidelines" an h1 * link directly to res.com releases page * link to changelogs in the readme * move full CHANGELOG.md message to readme * Delete CHANGELOG.md * BUILD.md is outdated and partially duplicated by DEPLOY.md * Update README.md * Update DEPLOY.md * clean up project structure docs
- Loading branch information
1 parent
d7044ee
commit 8983c74
Showing
5 changed files
with
186 additions
and
219 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,164 @@ | ||
| # 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 do have to pick and choose what features we should add. Code bloat is always a concern, and RES is already rather hefty. If you're unsure if your feature would appeal to a wide audience, please post about it on [/r/Enhancement](https://www.reddit.com/r/Enhancement/) or [contact @honestbleeps](https://www.reddit.com/message/compose/?to=honestbleeps) directly to ask. | ||
|
|
||
| 1. 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](https://www.reddit.com/r/Enhancement/wiki/rejectedfeaturerequests). | ||
|
|
||
| 1. To build the extension, see [Building development versions of the extension](#building-development-versions-of-the-extension). | ||
|
|
||
| 1. If you're adding new modules or hosts, see [Adding new files](#adding-new-files). | ||
|
|
||
| 1. Code style is enforced with ESLint and sass-lint. To check code style and autofix common errors, see [Lint and test commands](#lint-and-test-commands). | ||
|
|
||
| ## Project structure | ||
|
|
||
| #### Top level files and folders | ||
|
|
||
| - `.github/`: Github templates | ||
| - `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 | ||
| - `node/`: Node files | ||
| - `safari/`: Safari-specific RES files | ||
| - `tests/`: integration tests | ||
| - `utils/`: Misc RES utilities | ||
| - `package.json`: package info, dependencies | ||
| - `webpack.config.babel.js`: build script | ||
|
|
||
| ##### Chrome (`chrome/`) | ||
|
|
||
| - `background.entry.js`: the "background page" for RES, necessary for Chrome extensions | ||
| - `environment.js`: specific environment settings for Chrome | ||
| - `manifest.json`: the project manifest | ||
| - `options.html`: options page for chrome extensions | ||
|
|
||
| ##### Microsoft Edge (`edge/`) | ||
|
|
||
| - `edge.entry.js`: shim to allow chrome extension code usage | ||
| - `environment.js`: Edge-specific overrides of the Chrome environment | ||
| - `manifest.json`: the project manifest | ||
|
|
||
| ##### Firefox (`firefox/`) | ||
|
|
||
| - `background.entry.js`: the "background page" for RES, necessary for Firefox extensions | ||
| - `environment.js`: specific environment settings for Firefox | ||
| - `package.json`: the project manifest for the Firefox add-on | ||
|
|
||
| ##### Safari (`safari/`) | ||
|
|
||
| - `Info.plist`: the project manifest | ||
| - `background-safari.html`: the "background html page" for RES, necessary for Safari extensions | ||
| - `background.entry.js`: the "background page" for RES, necessary for Safari extensions | ||
| - `environment.js`: specific environment settings for Safari | ||
|
|
||
| ## Building development versions of the extension | ||
|
|
||
| #### First time installation | ||
|
|
||
| 1. Install [git](https://git-scm.com/). | ||
| 1. Install [node.js](https://nodejs.org) (version >= 6). | ||
| 1. Install [Python 2](https://www.python.org/downloads/) (*not* version 3). On Windows, please install the "Add python.exe to path" feature on the customize screen. | ||
| 1. Navigate to your RES folder. | ||
| 1. Run `npm install`. | ||
|
|
||
| Once done, you can build the extension by running `npm start` (see [Build commands](#build-commands)). | ||
|
|
||
| To load the extension into your browser, see [Loading RES into your browser](#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,safari,node`. `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](http://eslint.org/), as well as all `.scss` files with [sass-lint](https://github.com/sasstools/sass-lint). | ||
|
|
||
| **`npm run lint-fix`** will autofix any [fixable](http://eslint.org/docs/user-guide/command-line-interface#fix) lint issues. | ||
|
|
||
| **`npm run flow`** will run [Flow](https://flowtype.org/) 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](https://github.com/avajs/ava). | ||
|
|
||
| **`npm run test-integration -- <browsers>`** will run integration tests (in `tests/`) using [Nightwatch.js](http://nightwatchjs.org/). | ||
| Currently just `chrome` and `firefox` can be targeted. | ||
| To run integration tests locally, you must change `selenium_host`, `selenium_port`, `username`, and `access_key` in `nightwatch.conf.js` to correspond to your Selenium server. | ||
|
|
||
| #### Loading RES into your browser | ||
|
|
||
| ##### Chrome | ||
|
|
||
| 1. Go to `Menu->Tools->Extensions` and tick the `Developer Mode` checkbox | ||
| 2. Choose `Load unpacked extension` and point it to the `/dist/chrome` folder (not the `/chrome` folder). Make sure you only have one RES version running at a time. | ||
| 3. Any time you make changes to the script, 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. Choose `Load extension` on the extensions menu and select the `/dist/edge` folder (not the `/edge` folder). | ||
| 3. Any time you make changes to the extension, you must go back to the `Menu->Extensions` page, go to the extensions settings and `Reload` the extension. | ||
|
|
||
| ##### Firefox | ||
|
|
||
| 1. Install [jpm](https://developer.mozilla.org/en-US/Add-ons/SDK/Tools/jpm) using `npm`: `npm install -g jpm` | ||
| 2. Navigate to the `/dist/firefox` folder (not the `/firefox` folder) and run the command `jpm run`, which should launch a new Firefox browser using a temporary profile with only RES installed. | ||
|
|
||
| ##### Safari | ||
|
|
||
| 1. Open the `Preferences` by going to `Safari->Preferences` or pressing `⌘,`, then go to `Advanced` and check the checkbox for `Show Develop menu in menu bar`. | ||
| 2. Navigate to `Develop->Show Extension Builder` to open the extensions builder. Add a new extension by pressing the `+` in the bottom left and choosing `Add Extension`. | ||
| 3. Navigate to the `/dist/RES.safariextension` folder (not the `/safari` folder) for RES and select it. | ||
| 4. If you are using Safari 9+, you should be able to install the extension without enrolling in the [Apple Developer Program](https://developer.apple.com/programs/); however, the extension will be auto-uninstalled when you quit Safari. | ||
|
|
||
| If you use an older version of Safari or find the auto-uninstall annoying, you need to purchase a proper certificate by signing up for the [Apple Developer Program](https://developer.apple.com/programs/) (currently $99/yr). | ||
|
|
||
| ## Adding new files | ||
|
|
||
| #### Modules | ||
|
|
||
| See [`examples/module.js`](https://github.com/honestbleeps/Reddit-Enhancement-Suite/blob/master/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 modules must now have i18n implementations. Please see [here](https://github.com/honestbleeps/Reddit-Enhancement-Suite/blob/master/locales/locales/README.md) for details. | ||
|
|
||
| #### Media hosts | ||
|
|
||
| Please be sure that they support [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) so the sites do not need to be added as additional permissions, which has caused [headaches in the past](https://www.reddit.com/r/Enhancement/comments/1jskcm/announcement_chrome_users_did_your_res_turn_off/). | ||
|
|
||
| See [`examples/host.js`](https://github.com/honestbleeps/Reddit-Enhancement-Suite/blob/master/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. | ||
|
|
||
| #### Stylesheets | ||
|
|
||
| Create a new Sass partial under `lib/css/modules/` (with a leading underscore, e.g. `_myPartial.scss`). | ||
| Import the file in `lib/css/res.scss` (i.e. `@import 'modules/myPartial';`—do not include the underscore or file extension). | ||
|
|
||
| Body classes will be automatically added for boolean and enum options with the property `bodyClass: true`, in the form `.res-moduleId-optionKey` for boolean options (only when they're enabled), and `.res-moduleId-optionKey-optionValue` for enums. | ||
| This is the preferred way to create optional CSS; do not use `addCSS()` unless absolutely necessary (i.e. variable color, size, etc.). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,58 +1,38 @@ | ||
| # All browsers | ||
|
|
||
| 1. Run `npm run build` for the desired browser | ||
|
|
||
| #Chrome | ||
|
|
||
| `gulp build -b chrome` > `/dist/chrome` | ||
|
|
||
| **Upload at:** https://chrome.google.com/webstore/developer/dashboard | ||
| ## Chrome | ||
|
|
||
| Info: https://developer.chrome.com/webstore/publish | ||
|
|
||
| #Firefox | ||
| 1. Upload `chrome.zip` to https://chrome.google.com/webstore/developer/dashboard | ||
|
|
||
| `gulp build -b firefox` > `/dist/firefox` | ||
|
|
||
| Upload at: https://addons.mozilla.org/en-US/developers/addon/submit/1 | ||
| ## Firefox | ||
|
|
||
| Info: https://developer.mozilla.org/en-US/Add-ons/Distribution | ||
|
|
||
| #Safari | ||
| Info: https://developer.apple.com/library/safari/documentation/Tools/Conceptual/SafariExtensionGuide/DistributingYourExtension/DistributingYourExtension.html | ||
| 1. Run `npm run jpm xpi` or `npm run jpm-beta xpi` for stable/beta | ||
| 1. Upload `reddit-enhancement-suite.xpi` to https://addons.mozilla.org/en-US/developers/addon/submit/1 | ||
|
|
||
| # Safari 8 - Self-distribute | ||
| ## Safari | ||
|
|
||
| `gulp build -b safari` > `/dist/RES.safariextension` | ||
| Info: https://developer.apple.com/library/safari/documentation/Tools/Conceptual/SafariExtensionGuide/DistributingYourExtension/DistributingYourExtension.html | ||
|
|
||
| #### Safari 8 - Self-distribute | ||
|
|
||
| 1. Safari > Develop > Show extension builder | ||
| 1. Build package | ||
| 1. Upload .safariextz package to redditenhancementsuite.com | ||
| 1. Upload `.safariextz` package to redditenhancementsuite.com | ||
| 1. Update the redditnehancementsuite.com update manifest. | ||
|
|
||
| # Safari 9+ - Gallery | ||
|
|
||
| Follow Safari 8 rules, then submit to gallery: | ||
| https://developer.apple.com/safari/extensions/submission/ | ||
|
|
||
|
|
||
| #Opera | ||
|
|
||
| https://addons.opera.com/developer/ | ||
|
|
||
| # Opera 20+ | ||
|
|
||
| https://addons.opera.com/developer/ | ||
|
|
||
| `gulp build -b oblink` > `/dist/oblink` | ||
|
|
||
| Opera20 does have a "Pack extension" button on the extensions page, next to "Load unpacked extension" | ||
|
|
||
| "Navigator" is Opera's internal name for Opera20+ | ||
|
|
||
| # Opera 12.17 | ||
| #### Safari 9+ - Gallery | ||
|
|
||
| https://addons.opera.com/developer/ | ||
| 1. Follow Safari 8 rules | ||
| 1. Upload `.safariextz` to https://developer.apple.com/safari/extensions/submission/ | ||
|
|
||
| `gulp build -b opera` > `/dist/opera` | ||
| ## Opera | ||
|
|
||
| Info: https://dev.opera.com/extensions/publishing-guidelines/ | ||
|
|
||
| "Opera" is Opera's internal name for Opera12 | ||
| 1. Upload `chrome.zip` to https://addons.opera.com/developer/ |
Oops, something went wrong.