Instructions for testing scriptlet #172
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
antonok-edm
reviewed
May 1, 2024
README.md
Outdated
| ## Shipping and locally testing a new scriptlet | ||
|
|
||
| 1. In your local copy of 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 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. |
There was a problem hiding this comment.
Maybe worth mentioning that the rule can be added to brave://settings/shields/filters instead, as a simpler alternative?
There was a problem hiding this comment.
Oh can it? I wasn't aware. I thought you couldn't insert scriptlets via custom filters.
README.md
Outdated
| 1. In your local copy of 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 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 have a PR up for) that you create 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 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`. |
There was a problem hiding this comment.
minor, but if we can [brave-core-crx-packager](https://github.com/brave/brave-core-crx-packager) the links, that might make it easier to read this wall of instructions 😅
|
|
||
| 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. |
There was a problem hiding this comment.
Suggest mentioning here that you need to run npm run addScriptlet to generate the new resources.json file and commit it before pushing to the new remote branch.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.