Issue 131 - [Document projects consistently] Add a README.md to the adblockpluschrome repository

README.md

Index: README.md
===================================================================
new file mode 100644
--- /dev/null
+++ b/README.md
@@ -0,0 +1,61 @@
+Adblock Plus for Chrome, Opera and Safari
+=========================================
+

[kzar, 2015/02/17 09:38:05]

I think usually a brief introduction at the start of README files is useful to
quickly explain what the repository does and why.

+Building
+---------
+
+### Requirements
+
+- [Python 2.x](https://www.python.org)
+- [The Jinja2 module](http://jinja.pocoo.org/docs)

[Sebastian Noack, 2015/02/17 12:07:56]

PIL (Python Imaging Library) is required as well.

+- For signed Chrome and Opera builds: [M2Crypto module](https://github.com/martinpaljak/M2Crypto)
+- For signed Safari builds: A [patched version of the xar command line tool](https://github.com/mackyle/xar/)
+
+### Building the extension
+
+Run one of the following commands in the project directory, depending on your
+target platform:
+
+    ./build.py -t chrome build -k adblockpluschrome.pem
+    ./build.py -t opera build -k adblockplusopera.pem
+    ./build.py -t safari build -k adblockplussafari.pem
+
+This will create a build with a name in the form

[kzar, 2015/02/17 09:38:05]

Maybe mention something about how ensure_dependencies is called and pulls in a
few other repositories? (Might be useful to list them too.)

[Wladimir Palant, 2015/02/17 13:19:21]

I don't really want to document internals of buildtools here. I've added a
reference to the "dependencies" file however so whoever is interested can figure
out how this works.

Listing dependent repository: definitely not, that would duplicate state and
have the tendency to go out of sync.

+_adblockpluschrome-1.2.3.nnnn.crx_ or _adblockplussafari-1.2.3.nnnn.safariextz_.
+Note that you don't need an existing signing key for Chrome or Opera, a new key
+will be created automatically if the file doesn't exist. Safari on the other
+hand always requires a valid developer certificate, you need to get one in the
+Apple Developer Center first. _adblockplussafari.pem_ should contain your

[Sebastian Noack, 2015/02/17 12:07:56]

adblockplussafari.pem must also contain the key for your certificate.

+developer certificate as well as all the certificates it was signed with
+(Apple's root certificate and intermediate certificates) in PEM format.
+
+### Development environment

[kzar, 2015/02/17 09:38:05]

Maybe the development environment section should be above the building section.
It's a more common thing for new people to want to do.

[Wladimir Palant, 2015/02/17 13:19:21]

Most people seem to start by generating an installable build with a minor
modification. The development environment only becomes useful once you make many
changes.

+
+To simplify the process of testing your changes you can create an unpacked
+development environment. For that run one of the following commands:
+
+    ./build.py -t chrome devenv
+    ./build.py -t opera devenv
+    ./build.py -t safari devenv
+
+This will create a _devenv_ directoy in the repository. In Chrome and Opera you

[kzar, 2015/02/17 09:38:05]

I would use backticks ` instead of underscores _ for strings like "devenv".

[Wladimir Palant, 2015/02/17 13:19:21]

Blame fhd - he started doing that (probably because he dislikes code
formatting), and now we have to keep doing it for consistency ;)

+should load it as an unpacked extension directory. After making changes to the
+source code re-run the command to update the development environment, the
+extension should reload automatically after a few seconds.
+
+In Safari you should load _devenv/adblockplussafari.safariextension_ as unpacked
+extension directory. After making changes to the source code re-run the command
+to update the development environment. You will still need to reload the
+extension explicitly in the Extension Builder, Safari currently doesn't allow
+automating this action.
+
+Running the unit tests
+----------------------
+
+To verify your changes you can use the unit test suite located in the _qunit_
+directory of the repository. In order to run the unit tests go to the
+extension's Options page, open JavaScript Console and type in:

[Sebastian Noack, 2015/02/17 12:07:56]

Nit: open the JavaScript Console
          ^

+
+    location.href = "qunit/index.html";
+
+The unit test will run automatically once the page loads.

[Wladimir Palant, 2015/02/16 10:52:34]

Should be "unit tests" here of course.

[kzar, 2015/02/17 09:38:05]

Maybe add details of the code license(s) to the end of the readme here?

[Wladimir Palant, 2015/02/17 13:19:21]

This doesn't belong in the README file, it should be a separate LICENSE or
COPYING file.