Reddit Enhancement Suite (RES) is a suite of modules that enhance your Reddit browsing experience.
For general documentation, visit the Reddit Enhancement Suite Wiki.
Hi there! Thanks for checking out RES on GitHub. A few important notes:
-
RES is licensed under GPLv3, which means you're technically free to do whatever you wish in terms of redistribution as long as you maintain GPLv3 licensing. However, I ask out of courtesy that should you choose to release your own, separate distribution of RES, you please name it something else entirely. Unfortunately, I have run into problems in the past with people redistributing under the same name, and causing me tech support headaches.
-
I ask that you please do not distribute your own binaries of RES (e.g. with bugfixes, etc). The version numbers in RES are important references for tech support so that we can replicate bugs that users report using the same version they are, and when you distribute your own - you run the risk of polluting/confusing that. In addition, if a user overwrites his/her extension with your distributed copy, it may not properly retain their RES settings/data depending on the developer ID used, etc.
I can't stop you from doing any of this. I'm just asking out of courtesy because I already spend a great deal of time providing tech support and chasing down bugs, and it's much harder when people think I'm the support guy for a separate branch of code.
Thanks!
Steve Sobel steve@honestbleeps.com
Thinking about contributing to RES? Awesome! We just ask that you follow a few simple guidelines:
-
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 or contact @honestbleeps directly to ask.
-
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.
-
It would be greatly appreciated if you could stick to a few style guidelines. Some of these guidelines are NOT (yet!) strictly followed by RES because it originally started as an amalgamation of code from so many different sources. That said, we do hope to clean it up in due time... Some guidelines:
- please use tabs for indentation
- please use spaces in your
if
statements, e.g.if (foo === bar)
, notif(foo===bar)
- please comment your code!
- please, when possible, place
var
declarations all together at the top of a function - please consider installing a tool like JSHint or JSLint that will help enforce good JavaScript best practices!
In order to build the extension, the files from lib/
must be replicated (either via hard-links or grunt, see below) into the relevant browser directory.
README.md
– YOU ARE HERE, unless you're browing on GitHubchangelog.txt
– self-explanatorymakelinks.sh
– script to generate hard linksGruntfile.js
,package.json
– used for alternative build scriptslib/
– core RES codelib/modules/
– RES modulesChrome/
– Chrome-specific RES filesOpera/
– Opera-specific RES filesOperaBlink/
– Opera Blink (new Opera)-specific RES filesRES.safariextension/
– Safari-specific RES filesXPI/
– Firefox-specific RES filestests/
– RES tests, currently unused
background.js
– the "background page" for RES, necessary for Chrome extensionsmanifest.json
– the project manifesticon.png
,icon48.png
,icon128.png
– icons!jquery-1.10.2.min.map
– Chrome moans if this file doesn't exist
index.html
– the "background page" for RES, necessary for Opera extensionsconfig.xml
– Opera's equivalent of Chrome'smanifest.json
logo.gif
– a logo gif!
NOTE: This directory must have .safariextension
in the name, or Safari's extension builder pukes.
background-safari.html
– the "background page" for RES, necessary for Safari extensionsInfo.plist
– the project manifesticon.png
,icon48.png
,icon128.png
– icons!
NOTE: An XPI is a Firefox add-on, which is compiled using the Add-on SDK.
lib/main.js
– this is Firefox's sort of "background page" for RES, like what Chrome has, but just a JS filepackage.json
– the project manifest for the Firefox add-on
background.js
– the "background page" for RES, necessary for Chrome extensionsmanifest.json
– the project manifesticon.png
,icon48.png
,icon128.png
– icons!
In order to build a development version of RES, run makelinks.sh
to generate hard links into lib/
from the browser-specific folders. (This is necessary on Chrome.) NOTE: switching branches will break hard links, so you will need to rerun makelinks.sh
whenever you check out new code.
An alternative grunt build script is also provided; see "Using grunt instead of hard links" for more details.
- Go to
Menu->Tools->Extensions
and tick theDeveloper Mode
checkbox - Choose
Load unpacked extension
and point it to theChrome
folder. Make sure you only have one RES version running at a time. - Any time you make changes to the script, you must go back to the
Menu->Tools->Extensions
page andReload
the extension.
- Download the Add-on SDK.
- Start a terminal and source the Python script so that you can run the
cfx
commands. In Unix this is usually. bin/activate
orsource bin/activate
and in Windows this usually involves runningbin/activate.bat
. If you are not using Python 2, runvirtualenv --python=python2 .
and try again. - In the terminal,
cd
to theXPI
folder and run the commandcfx run
, which should launch a new Firefox browser using a temporary profile with only RES installed.
- Open the
Preferences
by going toSafari->Preferences
or pressing⌘
, then go toAdvanced
and check the checkbox forShow develop menu in menu bar
. - Navigate to
Develop->Show Extension Builder
to open the extensions menu. Add a new extension by pressing the+
in the bottom left and choosingAdd extension
. - Navigate to the
RES.safariextension
folder for RES and select it. - It will likely say you cannot install it because no Safari development certificate exists. You will need to visit the Safari Dev Center and create an account (right hand side).
- You then need to visit the Safari Developer Program site and sign up for a FREE account.
- You can then visit your member page and use the certificate utility to create a new Safari Developer Certificate. Follow the instructions to install the certificate. If you have an error involving it being signed by an unknown authority, then double click the certificate and under the
Trust
setting chooseAlways Trust
. You should then be able to install the extension from theExtension Builder
menu.
- Click
Tools->Extensions->Manage Extensions
- Drag the
config.xml
file in theOpera
directory in to the extensions window and release. You should now have installed the extension.
The above steps will fail if the makelinks.sh
or grunt build scripts have not been run before hand. Please ensure you only have one copy of RES running at a time.
RES can also be built using grunt. In order to use grunt, you will need to have node.js installed on your system.
If you have never used grunt before:
- Run
npm install -g grunt-cli
to install the grunt task runner. - Navigate to the RES directory in a console and run
npm install
to install all other dependencies.
Once done, you can build the extension by running grunt
.
For developing, run grunt
followed by the name of the browser you wish to develop on, such as grunt chrome
for Chrome or grunt firefox
for Firefox. Once run, grunt will start a watch task which will instantly copy any changes made in the lib/
directory over to the given browser's extension folder. You will need to stop and start grunt if you add any additional files.
To load the extension into your browser, see the "Building development versions of the extension" section above.