Setting up a local development environment is simple; it's all automated:
- Install Node.js - ensure to install the bundled Node Package Manager (npm), too.
Install Grunt by running the following shell command:
npm install -g grunt-cli
Confirm that the Grunt CLI is installed and works:
Clone the Dreditor repository:
git clone https://github.com/unicorn-fail/dreditor.git
Change into the new repository directory and install all dependencies:
cd dreditor npm install grunt install
Start a first Dreditor build by running:
Gruntfile.js in the top-level directory controls the compilation and build
To see a list of available grunt tasks, run:
$ grunt --help … Available tasks … install Installs dependencies. default Compiles code. dev:ff Compiles code to build a Firefox extension. (see watch:ff) watch:ff Enables real-time development for Firefox. test Runs tests. travis-ci Compiles code and runs tests. build Compiles code and builds all extensions. build:chrome Builds the Chrome extension. build:firefox Builds the Firefox extension. build:safari Builds the Safari extension. autoload:ff Loads the XPI extension into Firefox.
For more information about Grunt, see its getting started guide.
All set? Let's get ready to rumble!
|Main source code:|
||Base components, libraries, and utility functions.|
||Individual features split into one file per feature.|
||Templates for building browser extensions. (rarely touched)|
||Code compiled by grunt; e.g.,
||Fully packaged browser extensions.|
Create a new topic/feature branch.
Please do not work in the
Start watching file changes:
$ grunt watch
Check the console output for warnings and errors.
Write automated tests.
Later… see Automated testing chapter below.
Build an extension and manually test your changes.
See Manual testing chapter below.
Push your branch into your fork and create a pull request.
For debugging use
$.debug() or globals like
Some browsers have built-in support for automatically refreshing an extension via the command line.
→ Check the Manual testing chapter below to set up your browser.
For example, for Firefox, just simply run this:
$ grunt watch:ff
This will immediately perform an initial build (to simplify switching between branches), and upon any file change, a new extension is immediately built and loaded into your browser.
→ Simply reload a page on https://drupal.org/ and your changes are immediately active!
(Just reload, no need to force-refresh!)
- Two spaces for indentation. No tabs. Use
"\t"if you need a literal tab character in a string.
Exception: Markdown uses 4 spaces for indentation for maximum parser compatibility.
- No trailing white-space.
Exception: Markdown uses 2 trailing spaces to enforce a linebreak.
- Don't go overboard with white-space.
- No more than one assignment
- Delimit strings with single-quotes
', not double-quotes
? :ternary operators and complex
- Comment your code. Place comments before the line of code, not at the end of the line.
- When in doubt, stay consistent. Follow the conventions you see in the existing code.
When submitting a pull request, Travis CI will automatically…
Work In Progress… — More information on qunit testing coming soon.
Feature Branches and Pull Requests
Normally, branches and PRs are created from user-specific forks/repositories.
However, the maintainers MAY create public feature branches in the Dreditor repository under the following conditions:
The code is known to be incomplete and needs more work.
In this case, a public feature/topic branch in the Dreditor repository explicitly encourages co-maintainers to liberally improve the code through additional commits. However:
Commits MUST NOT be amended and the branch MUST NOT be rebased. Contributors MAY create PRs against the branch.
The branch represents a major refactoring/rewrite feature/topic on Dreditor's roadmap.
In this case, the public feature/topic branch exists in order to be developed in parallel to the current stable/mainline. If/when merged into the mainline, the merge of the feature/topic branch will denote a new major or minor version (e.g., v1 → v2).
Maintainers and contributors SHOULD create PRs against such major refactoring branches, since each change proposal SHOULD be reviewed independently.
Major feature/topic branches SHOULD have a maintainable scope. Therefore, they MAY be [criss-]cross-merged selectively into other major feature/topic branches, if necessary.
Sub-topics of major features/topics MAY be developed in public 'child' feature/topic branches, but it is RECOMMENDED to architect and design changes in a way to make them work independently to begin with.
In any case, every public feature/topic branch in the Dreditor repository MUST have a corresponding pull request (or issue) that holds the main discussion. A public feature/topic branch without a corresponding pull request (or issue) MAY be deleted without further notice. A public feature/topic branch SHOULD be deleted after merging it into the mainline.
- Installing a development build of Dreditor will replace the extension installed from dreditor.org.
- Whenever loading a custom build into your browser, make sure that you have only one Dreditor extension enabled at the same time.
- Go to
- Enable Developer mode.
- Click on Load unpacked extension…
- Browse to the
/build/chromedirectory and click
- Manually refresh the extensions page after each code change.
Requires the Firefox Add-on SDK, which should have been installed by the initial Setup already.
Install the Extension Auto-Installer Add-on.
wgetis installed. (Test with
# OSX brew|port install wget # Ubuntu sudo apt-get install wget
Alternatively, to manually load a single build without the autoinstaller:
- From the Tools menu, choose Add-ons.
- Use the gear menu and choose Install Add-on From File…
- Browse to
/release/firefoxand select the
Requires a (free) Safari Developer Certificate.
- Open the Preferences menu, choose the Advanced tab, and enable Show Develop menu in menu bar.
- From the Develop menu, choose Show Extension Builder.
- Click the + button in the bottom left corner of the window and choose Add Extension…
- Browse to the
/build/dreditor.safariextensiondirectory and click Select.
- Assuming a valid Safari Developer Certificate, click the Install button in
the top right.
- Upon first use of your Safari Developer Certificate, you will be asked to grant access.
- Click the Reload button in the Extension Builder window after each code change.