From 8983c74a89dbc1ca1b259ed55c918fa9a71945d6 Mon Sep 17 00:00:00 2001 From: Erik Desjardins Date: Fri, 6 Jan 2017 13:20:51 -0500 Subject: [PATCH] docs improvments (#3857) * 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 --- BUILD.md | 17 ----- CHANGELOG.md | 1 - CONTRIBUTING.md | 164 +++++++++++++++++++++++++++++++++++++++++++++++ DEPLOY.md | 56 ++++++---------- README.md | 167 ++---------------------------------------------- 5 files changed, 186 insertions(+), 219 deletions(-) delete mode 100644 BUILD.md delete mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md diff --git a/BUILD.md b/BUILD.md deleted file mode 100644 index 0587ddbc8f..0000000000 --- a/BUILD.md +++ /dev/null @@ -1,17 +0,0 @@ -### Building release versions of the extension ### - -This document is here for RES developer reference/testing. Please do not distribute your own binaries unofficially - see README.md for an explanation as to why. Thanks! - -**Chrome** - 1. Go to ``Settings->Extensions`` and choose ``Pack extension``. Choose the ``Chrome`` folder for RES. You can also choose to sign the extension with a private key. - 2. This will generate a ``.crx`` and ``.pem`` file for your extension that you can install by dropping the ``.crx`` file in ``Chrome``. - -**Firefox** - 1. Make sure you have the addons SDK installed as described in the development section. - 2. In your terminal, ``cd`` to the ``XPI`` folder and run ``cfx xpi``. This should build an ``.xpi`` file that you can use to install RES. - -**Opera** - 1. Opera extensions are simply zip files. So all you need to do is zip up the contents of the ``Opera`` folder, but not the folder itself. So the zip should contain everything inside the ``Opera`` folder. Rename the ``.zip`` file to have the extension ``.oex`` instead. See [here](http://dev.opera.com/articles/view/opera-extensions-hello-world/#packaging) for more information. - -**Safari** - 1. Navigate to the ``Extension Builder`` panel as described in the development instructions. Assuming you have followed those instructions and installed RES, you can now choose ``build`` in the top right. This will generate a ``.safariextz`` file (signed by your certificate) that you can use to install RES. diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 7a829cd271..0000000000 --- a/CHANGELOG.md +++ /dev/null @@ -1 +0,0 @@ -See the [`changelog/`](/changelog) directory for individual versions or https://www.redditenhancementsuite.com/ for all versions. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..bcc0b79e83 --- /dev/null +++ b/CONTRIBUTING.md @@ -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 [-- ]`** 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 [-- ]`** will clean `dist/`, then build RES (dev mode) a single time. + +**`npm run build [-- ]`** will clean `dist/`, then build RES (release mode). Each build output will be compressed to a .zip file in `dist/zip/`. + +`` 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 -- `** 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.). diff --git a/DEPLOY.md b/DEPLOY.md index cd6b6e2a68..de1d3c0d67 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -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/ diff --git a/README.md b/README.md index 5297913d0a..9f7036c00f 100644 --- a/README.md +++ b/README.md @@ -26,169 +26,10 @@ Thanks! Steve Sobel steve@honestbleeps.com -## Contributor guidelines +## Building and contributing -Thinking about contributing to RES? Awesome! We just ask that you follow a few simple guidelines: +See [CONTRIBUTING.md](/CONTRIBUTING.md). -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. +## Changelog -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 - - `locales`: RES i18n translations - - `node/`: Node files - - `safari/`: Safari-specific RES files - - `tests/`: integration tests - - `utils/`: Misc RES utilities - - `CHANGELOG.md`: self-explanatory - - `README.md`: YOU ARE HERE, unless you're browsing on GitHub - - `package.json`: package info, dependencies - - `webpack.config.babel.js`: build script - - `**/__tests__`: unit tests - -##### 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 [-- ]`** 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 [-- ]`** will clean `dist/`, then build RES (dev mode) a single time. - -**`npm run build [-- ]`** will clean `dist/`, then build RES (release mode). Each build output will be compressed to a .zip file in `dist/zip/`. - -`` 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 -- `** 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.). +See the [`changelog/`](/changelog) directory for individual versions or https://redditenhancementsuite.com/releases/ for all versions.