Instructions for testing scriptlet

README.md

@@ -107,3 +107,12 @@ The script should be run with no arguments.
 The resulting PEM file will be named `ad-block-updater-<component_id>.pem`. This new PEM file has to be uploaded to 1Password. See instructions [here](https://github.com/brave/internal/wiki/Uploading-new-adblock-list-PEM-file-to-1Password).
 
 We will need to run this script a second time to get values for the top-level `base64_public_key` and `component_id` fields. These will be different from the values for `list_text_component.base64_public_key` and `list_text_component.component_id` fields. This is necessary for iOS, see [tracking issue](https://github.com/brave/brave-ios/issues/5974).
+
+## Shipping and locally testing a new scriptlet
+
+1. In your local copy of [adblock-resources](https://github.com/brave/adblock-resources/), create a new git branch and add a new scriptlet using the instructions at the top of this README. You will manually add a new resource under `resources/`, and the building commands will auto-generate `dist/resources.json` and `metadata.json`. Here's a [simple example](https://github.com/brave/adblock-resources/pull/131). Push your branch and create a new PR. Don't merge in yet.
+2. You will also need an adblock rule to actually insert your scriptlet on a page. This will mean modifying a filter list that Brave ships. Go to your local copy of [adblock-lists](https://github.com/brave/adblock-lists). Create a new git branch and make your changes. This might look like a scriptlet injection for a site like `google.*##+js(brave-google-fix)` or something in `brave-specific.txt`. Here's a [simple example](https://github.com/brave/adblock-lists/pull/1310). Create a new PR by pushing to a new remote branch. Don't merge in yet.
+3. Now, we're ready to test changes locally. Go back to your `adblock-resources` git branch, and create another git branch. This git branch will be exclusively for testing. Modify `filter_lists/list_catalog.json` to point to the `https://raw.githubusercontent.com` URL for your new adblock-lists branch that you created in Step 2. For instance, if you're modifying `brave-specific.txt`, modify the `filter_lists/list_catalog.json` entry for "Brave Specific" to point to https://raw.githubusercontent.com/brave/adblock-lists/YOUR_BRANCH_NAME_FROM_STEP_2/brave-lists/brave-specific.txt. Push to a new remote branch - you don't need to create a PR for this branch since it will be purely for testing. 
+4. Now, go to your local copy of [brave-core-crx-packager](https://github.com/brave/brave-core-crx-packager). Change the `lib/adBlockRustUtils.js` file to point to your adblock-resources branches, not the `master` branches. You'll change the `braveResourcesUrl` variable to point to `https://raw.githubusercontent.com/brave/adblock-resources/YOUR_BRANCH_NAME_FROM_STEP_1/dist/resources.json` and `listCatalogUrl` to point to `https://raw.githubusercontent.com/brave/adblock-resources/YOUR_BRANCH_NAME_FROM_STEP_3/filter_lists/list_catalog.json`.
+5. Run `npm run data-files-ad-block-rust` in `brave-core-crx-packager`. This will generate files locally in `build/`. You need to copy over `resources.json` from `build/ad-block-updater/mfddibmblmbccpadfndgakiopmmhebop` to `~Library/Application Support/BraveSoftware/Brave-Browser-Development/mfddibmblmbccpadfndgakiopmmhebop/LATEST_VERSION/` (or your equivalent profile directory). Then, you will also need to copy over the test filter list that will insert the new resource. Copy `list.txt` from `build/ad-block-updater/iodkpdagapdfkphljnddpjlldadblomo` to `~Library/Application Support/BraveSoftware/Brave-Browser-Development/iodkpdagapdfkphljnddpjlldadblomo/LATEST_VERSION/`. You can find the mappings of component to component ID at this [wiki page](https://github.com/brave/brave-browser/wiki/Brave-Components#performing-an-on-demand-update-check). If you changed `brave-specific.txt`, that gets shipped as part of `Brave Ad Block Updater`, hence it's under `iodkpdagapdfkphljnddpjlldadblomo`.
+6. Restart the browser to pick up the new files.