Issue #6303 - Introduce basic foundation for automation in adblockplusui

README.md

 Shared Adblock Plus UI code
 ===========================
 
 The user interface elements defined in this repository will be used by various
 Adblock Plus products like Adblock Plus for Firefox. Their functionality can be
 tested within this repository, even though they might not work exactly the same
 as they will do in the final product.
 
 Installing dependencies
 -----------------------
 
-Once you have cloned the repository, go into the folder and run: `npm install`.
+Both [python 2](https://www.python.org/downloads/) and [node](https://nodejs.org/en/), as well as [npm](https://www.npmjs.com), are required to contribute to this repository.

[Thomas Greiner, 2018/02/12 13:01:43]

Suggestion: We don't have a coding style for Markdown but I noticed some
arbitrary line breaks in this file so what about sticking to the 80 characters
line length that all the other text in this file conforms to?

[a.giammarchi, 2018/02/12 14:52:55]

agreed but this has been already merged so I'll keep that in mind for the next
time. Does it sound reasonable?

 
-Both node dependencies and one python script will run to setup the folder.

[Thomas Greiner, 2018/01/23 19:22:35]

Detail: I know it's nit-picking but I noticed that you're spelling it "Python"
in the very next sentence whereas here you're writing "python" and "node" with
lower-case letters. So that inconsistency was a bit too obvious for me not to
point out since those two are so close together. :)

+If you are installing `node` in ArchLinux, please remember to install `npm` too.
 
-You need Python version 2 to ensure a successful `./buildtools` setup.

[Thomas Greiner, 2018/01/23 19:22:35]

What about mentioning that as part of a list of requirements? Because not only
do we require Python 2 but also Node and npm.

[a.giammarchi, 2018/01/24 10:52:36]

Python 2 (or python 2) is available by default in both macOS and Linux (AFAIK
including WSL) so I didn't think about it but you are right, it should be as
clear as possible that to contribute you need node, npm, and python (so, is
python better than Python ? or if Pytno, should I write NodeJS too ?)

[Thomas Greiner, 2018/01/24 11:56:33]

I guess that's a personal preference so as long as we're consistent with how we
refer to them anything should be fine. :)

Personally, I tend to check the official homepage/repository to see how they're
writing it themselves.

+After cloning this repository, enter into its folder and run: `npm install`.
+
+This should create and populate, both `./node_modules` folder and the `./buildtools` one.
 
 Directory structure
 -------------------
 
 * Top-level files:
   * `firstRun.html` and `firstRun.js`: First-run page, see below
   * `i18n.js`: Localization functions, should be included by all pages.
   * `messageResponder.js`: Script to be used on the background page to respond
     to messages sent by UI code.
   * `background.html`, `background.js`: Test implementation of the background
@@ skipping 13 matching lines @@
   *not to be imported*, these files should rather be replaced by
   product-specific versions providing the same interface.
 
 Testing
 -------
 
 In Firefox the HTML pages can be opened directly from the file system
 and should be fully functional. Due to security restrictions in Chrome, there
 you need to pass in the `--allow-file-access-from-files` command line flag when
 starting the application. Alternatively, you can run `npm start` and open
-the HTML pages under URLs like `http://127.0.0.1:5000/firstRun.html`.
+the HTML pages under URL shown shown in the terminal (example: http://127.0.0.1:8080).
+
+You can pass along to underlying [http-server](https://www.npmjs.com/package/http-server)
+program any arguments via `--` as in:
+```sh
+npm start -- -p 5000 -c-1
+```
 
 Various aspects of the pages can be tested by setting parameters in the URL.
 The only universal parameter is `locale`, e.g. `?locale=es-AR`. This parameter
 overrides browser's locale which will be used by default.
 
 Linting
 -------
 
-You can lint both JS and CSS at once via `npm run lint`.
+You can lint all options via `npm run lint`.
 
-You can also run only JS via `npm run lint:js`, or CSS via `npm run lint:css`.
+You can also run specific target linting via `npm run lint:js` or, once available, via `npm run lint:css`.
 
 Remember, both `eslint` and `stylelint` can help fixing issues via `--fix` flag.
 
-You can try as example via `npx stylelint --fix skin/real-file-name.css`.

[Thomas Greiner, 2018/01/23 19:22:35]

I assume it's a typo but in case it's not: What does "npx" stand for?

[a.giammarchi, 2018/01/24 10:52:36]

npx is the "node package executable" binary that comes with npm 5.2 or higher.
https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b

Instead of needing to create a script entry in the package.json file, with a
name, and some bash script to pass arguments, and then run it through `npm run
executable-module arg1 argn`, you can just `npx executable-module arg1 argn`
without needing any entry in package.json.

It's a way to quickly use modules with an executable beside the building
process. It's a developers oriented shortcut and super handy to avoid global
installations. You just npx eslint, or whatever you want, and that's it, ready
to test.

As summary, I'll put a link to the npx page so others that didn't know npx will
learn about it.

[Thomas Greiner, 2018/01/24 11:56:33]

I didn't know this was included in npm so thanks for the explanation.
Sounds good.

+You can try as example via [npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b)
+which should be provided automatically when you install `npm`.
+
+```sh
+npx stylelint --fix skin/real-file-name.css
+```
 
 Translations
 ------------
 
 Translations for the strings in this project are managed using the online
 [Crowdin platform][crowdin]. To synchronise with Crowdin you can use the build
 script. To get a list of the possible commands type `./build.py help` at
 the command line. (You will also need the Crowdin API key for the project.)
 
 firstRun.html
@@ skipping 44 matching lines @@
   errors when adding new filters on the options page
 * `blockedURLs`: a comma-separated list of URLs that should be considered
   blocked (necessary to test the check for blocked scripts in sharing buttons).
 * `downloadStatus`: sets downloadStatus parameter for filter lists, can be used
   to trigger various filter list download errors
 * `platform=chromium`: shows the opt-out for the developer tools panel
 * `showNotificationUI=true`: simulates user having opted-out of notifications
 
 
 [crowdin]: https://crowdin.com