-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
216 lines (167 loc) · 21.8 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Home - Documentation</title>
<script src="scripts/prettify/prettify.js"></script>
<script src="scripts/prettify/lang-css.js"></script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
<script src="scripts/nav.js" defer></script>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
<input type="checkbox" id="nav-trigger" class="nav-trigger" />
<label for="nav-trigger" class="navicon-button x">
<div class="navicon"></div>
</label>
<label for="nav-trigger" class="overlay"></label>
<nav >
<input type="text" id="nav-search" placeholder="Search" />
<h2><a href="index.html">Home</a></h2><h2><a href="https://github.com/toolbox-team/reddit-moderator-toolbox" target="_blank" class="menu-item" >Github</a></h2><h2><a href="https://www.reddit.com/r/toolbox" target="_blank" class="menu-item" >Subreddit</a></h2><h3>Classes</h3><ul><li><a href="Module.html">Module</a><ul class='methods'><li data-type='method'><a href="Module.html#get">get</a></li><li data-type='method'><a href="Module.html#getEnabled">getEnabled</a></li><li data-type='method'><a href="Module.html#init">init</a></li><li data-type='method'><a href="Module.html#set">set</a></li><li data-type='method'><a href="Module.html#setEnabled">setEnabled</a></li></ul></li><li><a href="TBListener.html">TBListener</a><ul class='methods'><li data-type='method'><a href="TBListener.html#clear">clear</a></li><li data-type='method'><a href="TBListener.html#on">on</a></li><li data-type='method'><a href="TBListener.html#start">start</a></li><li data-type='method'><a href="TBListener.html#stop">stop</a></li></ul></li></ul><h3>Global</h3><ul><li><a href="global.html#DISPLAY_BOTTOM">DISPLAY_BOTTOM</a></li><li><a href="global.html#DISPLAY_CENTER">DISPLAY_CENTER</a></li><li><a href="global.html#FEEDBACK_NEGATIVE">FEEDBACK_NEGATIVE</a></li><li><a href="global.html#FEEDBACK_NEUTRAL">FEEDBACK_NEUTRAL</a></li><li><a href="global.html#FEEDBACK_POSITIVE">FEEDBACK_POSITIVE</a></li><li><a href="global.html#ModNotesBadge">ModNotesBadge</a></li><li><a href="global.html#ModNotesPager">ModNotesPager</a></li><li><a href="global.html#ModNotesPopup">ModNotesPopup</a></li><li><a href="global.html#NoteTableRow">NoteTableRow</a></li><li><a href="global.html#RandomFeedback">RandomFeedback</a></li><li><a href="global.html#RandomQuote">RandomQuote</a></li><li><a href="global.html#TBsettingsObject">TBsettingsObject</a></li><li><a href="global.html#actionButton">actionButton</a></li><li><a href="global.html#addModSubsToSidebar">addModSubsToSidebar</a></li><li><a href="global.html#addToSiteTable">addToSiteTable</a></li><li><a href="global.html#addTrophiesToSidebar">addTrophiesToSidebar</a></li><li><a href="global.html#alert">alert</a></li><li><a href="global.html#baseDomain">baseDomain</a></li><li><a href="global.html#browserName">browserName</a></li><li><a href="global.html#buildSha">buildSha</a></li><li><a href="global.html#buildType">buildType</a></li><li><a href="global.html#button">button</a></li><li><a href="global.html#checkForActions">checkForActions</a></li><li><a href="global.html#cleanSubredditName">cleanSubredditName</a></li><li><a href="global.html#clearCache">clearCache</a></li><li><a href="global.html#colorNameToHex">colorNameToHex</a></li><li><a href="global.html#contextTrigger">contextTrigger</a></li><li><a href="global.html#createDeferredProcessQueue">createDeferredProcessQueue</a></li><li><a href="global.html#daysToMilliseconds">daysToMilliseconds</a></li><li><a href="global.html#debounce">debounce</a></li><li><a href="global.html#debugInformation">debugInformation</a></li><li><a href="global.html#defaultNoteLabelValueToLabelType">defaultNoteLabelValueToLabelType</a></li><li><a href="global.html#delay">delay</a></li><li><a href="global.html#displayNotes">displayNotes</a></li><li><a href="global.html#domain">domain</a></li><li><a href="global.html#escapeHTML">escapeHTML</a></li><li><a href="global.html#fetchModSubs">fetchModSubs</a></li><li><a href="global.html#fetchNewsNotes">fetchNewsNotes</a></li><li><a href="global.html#figureOutMulti">figureOutMulti</a></li><li><a href="global.html#filterModdable">filterModdable</a></li><li><a href="global.html#getActions">getActions</a></li><li><a href="global.html#getAllModNotes">getAllModNotes</a></li><li><a href="global.html#getAnonymizedSettings">getAnonymizedSettings</a></li><li><a href="global.html#getCache">getCache</a></li><li><a href="global.html#getContextURL">getContextURL</a></li><li><a href="global.html#getLastVersion">getLastVersion</a></li><li><a href="global.html#getLatestModNote">getLatestModNote</a></li><li><a href="global.html#getModSubs">getModSubs</a></li><li><a href="global.html#getModlog">getModlog</a></li><li><a href="global.html#getRandomNumber">getRandomNumber</a></li><li><a href="global.html#getSetting">getSetting</a></li><li><a href="global.html#getSettingAsync">getSettingAsync</a></li><li><a href="global.html#getSettings">getSettings</a></li><li><a href="global.html#getSubmissionFullname">getSubmissionFullname</a></li><li><a href="global.html#getSubredditColors">getSubredditColors</a></li><li><a href="global.html#getTime">getTime</a></li><li><a href="global.html#getToolboxDevs">getToolboxDevs</a></li><li><a href="global.html#handleMessage">handleMessage</a></li><li><a href="global.html#handleTBThings">handleTBThings</a></li><li><a href="global.html#handleThing">handleThing</a></li><li><a href="global.html#hideModActionsThings">hideModActionsThings</a></li><li><a href="global.html#htmlDecode">htmlDecode</a></li><li><a href="global.html#htmlEncode">htmlEncode</a></li><li><a href="global.html#humaniseDays">humaniseDays</a></li><li><a href="global.html#init">init</a></li><li><a href="global.html#initialLoadPromise">initialLoadPromise</a></li><li><a href="global.html#isConfigValidVersion">isConfigValidVersion</a></li><li><a href="global.html#isEquivalent">isEquivalent</a></li><li><a href="global.html#isModSub">isModSub</a></li><li><a href="global.html#isNewModmail">isNewModmail</a></li><li><a href="global.html#isOldReddit">isOldReddit</a></li><li><a href="global.html#labelColors">labelColors</a></li><li><a href="global.html#labelNames">labelNames</a></li><li><a href="global.html#link">link</a></li><li><a href="global.html#listenerAliases">listenerAliases</a></li><li><a href="global.html#literalRegExp">literalRegExp</a></li><li><a href="global.html#makeCommentThread">makeCommentThread</a></li><li><a href="global.html#makeQueueOverlay">makeQueueOverlay</a></li><li><a href="global.html#makeSingleComment">makeSingleComment</a></li><li><a href="global.html#makeSubmissionEntry">makeSubmissionEntry</a></li><li><a href="global.html#makeUserSidebar">makeUserSidebar</a></li><li><a href="global.html#messageHandlers">messageHandlers</a></li><li><a href="global.html#millisecondsToDays">millisecondsToDays</a></li><li><a href="global.html#minutesToMilliseconds">minutesToMilliseconds</a></li><li><a href="global.html#modbarExists">modbarExists</a></li><li><a href="global.html#moveArrayItem">moveArrayItem</a></li><li><a href="global.html#newModmailSidebar">newModmailSidebar</a></li><li><a href="global.html#niceDateDiff">niceDateDiff</a></li><li><a href="global.html#notification">notification</a></li><li><a href="global.html#overlay">overlay</a></li><li><a href="global.html#pager">pager</a></li><li><a href="global.html#pagerForItems">pagerForItems</a></li><li><a href="global.html#parseComments">parseComments</a></li><li><a href="global.html#parser">parser</a></li><li><a href="global.html#popup">popup</a></li><li><a href="global.html#progressivePager">progressivePager</a></li><li><a href="global.html#purify">purify</a></li><li><a href="global.html#purifyObject">purifyObject</a></li><li><a href="global.html#regExpEscape">regExpEscape</a></li><li><a href="global.html#relativeTime">relativeTime</a></li><li><a href="global.html#reloadIframe">reloadIframe</a></li><li><a href="global.html#reloadToolbox">reloadToolbox</a></li><li><a href="global.html#remove">remove</a></li><li><a href="global.html#removeLastDirectoryPartOf">removeLastDirectoryPartOf</a></li><li><a href="global.html#removeQuotes">removeQuotes</a></li><li><a href="global.html#replaceAll">replaceAll</a></li><li><a href="global.html#replaceTokens">replaceTokens</a></li><li><a href="global.html#saneSort">saneSort</a></li><li><a href="global.html#saneSortAs">saneSortAs</a></li><li><a href="global.html#saveSettingsToBrowser">saveSettingsToBrowser</a></li><li><a href="global.html#searchProfile">searchProfile</a></li><li><a href="global.html#setCache">setCache</a></li><li><a href="global.html#setSetting">setSetting</a></li><li><a href="global.html#setSettingAsync">setSettingAsync</a></li><li><a href="global.html#settings">settings</a></li><li><a href="global.html#settingsToObject">settingsToObject</a></li><li><a href="global.html#shortVersion">shortVersion</a></li><li><a href="global.html#showNote">showNote</a></li><li><a href="global.html#sortBy">sortBy</a></li><li><a href="global.html#standardColors">standardColors</a></li><li><a href="global.html#stringToColor">stringToColor</a></li><li><a href="global.html#submissionFullnamesCache">submissionFullnamesCache</a></li><li><a href="global.html#tbRedditEvent">tbRedditEvent</a></li><li><a href="global.html#textFeedback">textFeedback</a></li><li><a href="global.html#timeConverterRead">timeConverterRead</a></li><li><a href="global.html#title_to_url">title_to_url</a></li><li><a href="global.html#toolboxVersion">toolboxVersion</a></li><li><a href="global.html#toolboxVersionName">toolboxVersionName</a></li><li><a href="global.html#typeNames">typeNames</a></li><li><a href="global.html#unescapeHTML">unescapeHTML</a></li><li><a href="global.html#unescapeJSON">unescapeJSON</a></li><li><a href="global.html#verifiedSettingsSave">verifiedSettingsSave</a></li><li><a href="global.html#watchForURLChanges">watchForURLChanges</a></li><li><a href="global.html#wrapWithLastValue">wrapWithLastValue</a></li><li><a href="global.html#zlibDeflate">zlibDeflate</a></li><li><a href="global.html#zlibInflate">zlibInflate</a></li></ul>
</nav>
<div id="main">
<section class="package">
<h3> </h3>
</section>
<section class="readme usertext">
<article><h1>Contributor guidelines</h1>
<p>Thinking about contributing to toolbox? Awesome! We accept a variety of different types of contributions:</p>
<h2>Issues and Ideas</h2>
<p>We welcome bug reports and feature requests. Please submit those to <a href="https://www.reddit.com/r/toolbox">/r/toolbox</a> rather than creating a Github issue unless you've already talked to us about your issue or idea, to help us minimize clutter.</p>
<h2>Documentation</h2>
<p>Our <a href="https://www.reddit.com/r/toolbox/wiki">user documentation pages</a> can always use help, and contributing doesn't require coding knowledge! If you know how to use Toolbox and want to help the project, check out our docs wiki.</p>
<p>We also accept edits to <a href="https://github.com/toolbox-team/reddit-moderator-toolbox/wiki">our Github wiki</a>, which holds documentation for our internal processes and for third-party developers looking to integrate toolbox settings and data into their tools. Working on it will require a fair bit of techincal knowledge, but we welcome feedback and changes there as well.</p>
<h2>Contributing Code</h2>
<p>We review and accept pull requests for new features and bug fixes. Here's some information that will be useful for developers looking to get started:</p>
<h3>Code/Programming style guidelines</h3>
<p>Since toolbox is a project that receives contributions from multiple people from various programming backgrounds, it's important to be aware of style conventions. We have <a href="https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Programming-style-guide">a dev wiki article</a> that explains some of our setup.</p>
<h3>Contributing completely new functionality</h3>
<p>We welcome new functionality, however it is always possible that someone is already working on something you have thought up or that we have not implemented something deliberately. So if you are considering coding new functionality it is always a good idea to first check. Simply make an issue here on GitHub or <a href="https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Contacting-the-toolbox-team">contact the team on Discord or IRC</a>.</p>
<h3>Existing utility functions</h3>
<p>We have a lot of utility functions in toolbox ready to be used for background operations as well as interface building. So when you need a specific sort of function it is always a good idea make sure to check if it does not already exist.</p>
<p>You can find the documentation for all this on the following locations:</p>
<ul>
<li><a href="https://toolbox-team.github.io/source-docs/">JSDoc source code documentation</a> Note: Not yet entirely complete, more documentation for code is an ongoing effort.</li>
<li><a href="https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Toolbox-Module-Structure">Toolbox module documentation</a> details how the general toolbox module structure works.</li>
<li>Team members on Discord. We try to keep the documentation updated but it very much is a work in progress. So when things are unclear don't be afraid to simply ask.</li>
</ul>
<h2>Project structure</h2>
<ul>
<li><code>/</code>: root directory containing scripting for building toolbox and configuration for development related things (linting, git configuration files).</li>
<li><code>extension/</code>: root directory of the extension itself. Contains the manifests. From here the unpacked extension can be loaded for development.</li>
<li><code>extension/data/</code>: Directory containing the functional code of toolbox. All files starting with <code>tb</code> are toolbox core scripts.</li>
<li><code>extension/data/tbmodule.jsx</code>: Modules are loaded into toolbox through this.</li>
<li><code>extension/data/tbstorage.js</code>: Everything storage related.</li>
<li><code>extension/data/tbui.js</code>: Handles creating UI elements.</li>
<li><code>extension/data/tbhelpers.js</code>: Contains standalone utility functions. Public functions all are part of the <code>TBHelpers</code> object.</li>
<li><code>extension/data/tbapi.ts</code>: Contains reddit api utility functions. Public functions all are part of the <code>TBApi</code> object.</li>
<li><code>extension/data/tbcore.js</code>: TBCore is one of the core blocks on which toolbox is build. It contains a lot of information about the state of toolbox and reddit.</li>
<li><code>extension/data/background/</code>: Contains extension background scripts</li>
<li><code>extension/data/images/</code>: Images used by toolbox.</li>
<li><code>extension/data/modules/</code>: Contains the individual toolbox modules.</li>
<li><code>extension/data/styles/</code>: Contains all CSS</li>
</ul>
<h2>Building, testing, and dev scripts</h2>
<p>Building the extension is relatively easy through <a href="https://nodejs.org/en/">Node.js</a>. We use <a href="https://www.rollupjs.org/">Rollup</a> to bundle the extension's Javascript code and manually copy over assets including images and the <code>manifest.json</code> file via <a href="https://www.npmjs.com/package/rollup-plugin-copy">rollup-plugin-copy</a>. Additionally, some browser-specific processing is applied to the manifest to work around some browser-specific incompatibilities. Build output goes to <code>build/chrome</code> and <code>build/firefox</code>.</p>
<pre class="prettyprint source lang-sh"><code>$ npm install # Install dependencies
$ npm run build # Build extension
$ npm run build:watch # Automatically rebuild on file changes
$ npm run docs # Build documentation of internal interfaces
</code></pre>
<p>You won't need to mess with these for development, but <code>npm run build</code> takes the following environment variables:'</p>
<ul>
<li><code>BUILD_TYPE</code>: One of <code>dev</code>, <code>beta</code>, <code>stable</code>; defaults to <code>dev</code>. Beta and stable builds are meant for distribution to others and are typically made by CI; dev builds are almost always what you want when building locally.</li>
<li><code>BUILD_SHA</code>: Commit hash of the commit that's being built. Leaving it unset for dev builds is normal, since your changes probably aren't committed yet anyway, but the build will yell at you if you try to generate a <code>beta</code> or <code>stable</code> release without it since those are meant to be distributed to others.</li>
</ul>
<p>Once you've built the extension, you can load it up in your browser for testing:</p>
<h2>Testing on Chromium-Based browsers</h2>
<ul>
<li>Go to <code>chrome://extensions</code> (<code>edge://extensions</code>, etc.).</li>
<li>Check the "Developer mode" checkbox if it's not already checked.</li>
<li>Click the "Load unpacked extension..." button.</li>
<li>Chromium asks for the extension directory, so load the <code>build/chrome</code> directory.</li>
</ul>
<h2>Testing on Firefox</h2>
<ul>
<li>Go to <code>about:debugging</code>.</li>
<li>Click "This Firefox" in the sidebar.</li>
<li>Click "Load Temporary Add-on...".</li>
<li>Firefox asks for a zip or the manifest file, so load the <code>build/firefox/manifest.json</code> file.</li>
</ul>
<h2>Maintainer Information: Versioning</h2>
<p>Toolbox version numbers are identified by a major.minor.patch stable release identifier (e.g. <code>6.1.13</code>) and an incrementing build number within each stable release. A beta release uses the version number of the stable release it will eventually be a part of (i.e. beta releases should not use a major.minor.patch which is already used by a stable release). Whenever a release is first made on a new major.minor.patch version (beta or stable), the build number resets to 1; subsequent releases increment the build number further, including the final stable release.</p>
<p>Git tags of stable releases use only the major.minor.patch identifier with a <code>v</code> prefix (e.g. <code>v6.1.13</code>). Beta releases also include a <code>-beta.#</code> suffix, where <code>#</code> is the build number (e.g. <code>v7.0.0-beta.1</code>).</p>
<p>The manifest <code>version</code> field combines the major.minor.patch and the build number into a single four-segment version string (e.g. <code>6.1.13.1</code>). The <code>version_name</code> field uses only the major.minor.patch, in addition to whatever fun name is selected for the release (e.g. <code>6.1.13 "Delaying Donkey"</code>).</p>
<p>As an example, a release timeline might look something like this:</p>
<table>
<thead>
<tr>
<th>Manifest <code>version</code></th>
<th>Git tag</th>
<th>Release type</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>6.1.13.1</code></td>
<td><code>v6.1.13</code></td>
<td>stable</td>
</tr>
<tr>
<td><code>7.0.0.1</code></td>
<td><code>v7.0.0-beta.1</code></td>
<td>beta</td>
</tr>
<tr>
<td><code>7.0.0.2</code></td>
<td><code>v7.0.0-beta.2</code></td>
<td>beta</td>
</tr>
<tr>
<td><code>7.0.0.3</code></td>
<td><code>v7.0.0</code></td>
<td>stable</td>
</tr>
</tbody>
</table>
<h3>Tagging a New Release</h3>
<ol>
<li>
<p>Make sure the working directory is clear and you're on the <code>master</code> branch.</p>
</li>
<li>
<p>Update <code>firefox_manifest.json</code>'s <code>strict_min_version</code> to the latest ESR version of Firefox. <a href="https://whattrainisitnow.com/calendar/">Here's a link to the FF release calendar for reference</a>. (TODO: automate this somehow. this is necessary because AMO will eventually prevent you from uploading extensions where this number is too low, but we want to set it to <em>something</em> to prevent people from using the extension in browser versions where it will obviously not work.)</p>
</li>
<li>
<p>Run <code>npm run release</code>. This script will prompt you for the new four-segment version number, then the release name.</p>
<ul>
<li>Ensure the major.minor.patch is set correctly. You should only need to update this if the previous release was a stable release.</li>
<li>If the previous release was a beta release, increment the build number by 1. If the previous release was a stable release, instead reset the build number <em>to</em> 1.</li>
<li>We generally only change the release name for major or minor bumps. If you're making a stable release and didn't change this during the beta series, make sure you update this to something appropriate for the new release. Tradition dictates it should be an adjective related to the development of the release, and an animal which start with the same letter.</li>
</ul>
<p>The script will then automatically commit and tag the release in your local clone.</p>
</li>
<li>
<p>Verify that the commit created by the release script contains nothing except changes to the version strings in the manifest files.</p>
</li>
<li>
<p>Push the commit and tag: <code>git push && git push --tags</code>.</p>
</li>
</ol>
<p>Once your tag is pushed to Github, the CI pipeline will generate release builds and automatically submit them to extension stores. Beta releases will be sent only to the beta listings; stable releases will result in updates to both the stable <em>and</em> beta listings, with the beta listing receiving a beta-flagged build containing otherwise the same code.</p></article>
</section>
</div>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.2</a> on Mon Dec 30 2024 00:15:02 GMT+0000 (Coordinated Universal Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
</footer>
<script>prettyPrint();</script>
<script src="scripts/polyfill.js"></script>
<script src="scripts/linenumber.js"></script>
<script src="scripts/search.js" defer></script>
</body>
</html>