Merge branch 'dev' into feat/improve-fingerprint-api

# Conflicts:
#	src/main/kotlin/app/revanced/patcher/patch/BytecodePatchContext.kt
#	src/main/kotlin/app/revanced/patcher/patch/Patch.kt
#	src/test/kotlin/app/revanced/patcher/PatcherTest.kt

.editorconfig

@@ -0,0 +1,3 @@
+[*.{kt,kts}]
+ktlint_code_style = intellij_idea
+ktlint_standard_no-wildcard-imports = disabled

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,7 +1,7 @@
 name: 🐞 Bug report
 description: Report a bug or an issue.
-title: 'bug: '
-labels: ['Bug report']
+title: "bug: "
+labels: ["Bug report"]
 body:
   - type: markdown
     attributes:
@@ -69,8 +69,9 @@ body:
         # ReVanced Patcher bug report
 
         Before creating a new bug report, please keep the following in mind:
-        
-        - **Do not submit a duplicate bug report**: You can review existing bug reports [here](https://github.com/ReVanced/revanced-patcher/labels/Bug%20report).
+
+        - **Do not submit a duplicate bug report**: Search for existing bug reports [here](https://github.com/ReVanced/revanced-patcher/issues?q=label%3A%22Bug+report%22).
+        - **Review the contribution guidelines**: Make sure your bug report adheres to it. You can find the guidelines [here](https://github.com/ReVanced/revanced-patcher/blob/main/CONTRIBUTING.md).
         - **Do not use the issue page for support**: If you need help or have questions, check out other platforms on [revanced.app](https://revanced.app).
   - type: textarea
     attributes:
@@ -100,7 +101,7 @@ body:
       label: Acknowledgements
       description: Your bug report will be closed if you don't follow the checklist below.
       options:
-        - label: This issue is not a duplicate of an existing bug report.
+        - label: I have checked all open and closed bug reports and this is not a duplicate.
           required: true
         - label: I have chosen an appropriate title.
           required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,7 +1,7 @@
 name: ⭐ Feature request
 description: Create a detailed request for a new feature.
-title: 'feat: '
-labels: ['Feature request']
+title: "feat: "
+labels: ["Feature request"]
 body:
   - type: markdown
     attributes:
@@ -70,7 +70,8 @@ body:
 
         Before creating a new feature request, please keep the following in mind:
 
-        - **Do not submit a duplicate feature request**: You can review existing feature requests [here](https://github.com/ReVanced/revanced-patcher/labels/Feature%20request).
+        - **Do not submit a duplicate feature request**: Search for existing feature requests [here](https://github.com/ReVanced/revanced-patcher/issues?q=label%3A%22Feature+request%22).
+        - **Review the contribution guidelines**: Make sure your feature request adheres to it. You can find the guidelines [here](https://github.com/ReVanced/revanced-patcher/blob/main/CONTRIBUTING.md).
         - **Do not use the issue page for support**: If you need help or have questions, check out other platforms on [revanced.app](https://revanced.app).
 
   - type: textarea
@@ -85,7 +86,7 @@ body:
       label: Motivation
       description: |
         A strong motivation is necessary for a feature request to be considered.
-        
+
         - Why should this feature be implemented? 
         - What is the explicit use case?
         - What are the benefits?
@@ -98,7 +99,7 @@ body:
       label: Acknowledgements
       description: Your feature request will be closed if you don't follow the checklist below.
       options:
-        - label: This issue is not a duplicate of an existing feature request.
+        - label: I have checked all open and closed feature requests and this is not a duplicate.
           required: true
         - label: I have chosen an appropriate title.
           required: true

.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    labels: []
+    directory: /
+    target-branch: dev
+    schedule:
+      interval: monthly
+
+  - package-ecosystem: npm
+    labels: []
+    directory: /
+    target-branch: dev
+    schedule:
+      interval: monthly
+
+  - package-ecosystem: gradle
+    labels: []
+    directory: /
+    target-branch: dev
+    schedule:
+      interval: monthly

.github/workflows/build_pull_request.yml

@@ -0,0 +1,25 @@
+name: Build pull request
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - dev
+
+jobs:
+  release:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Cache Gradle
+        uses: burrunan/gradle-cache-action@v1
+
+      - name: Build
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: ./gradlew build --no-daemon

.github/workflows/release.yml

@@ -6,14 +6,13 @@ on:
     branches:
       - main
       - dev
-  pull_request:
-    branches:
-      - main
-      - dev
 
 jobs:
   release:
     name: Release
+    permissions:
+      contents: write
+      packages: write
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -24,25 +23,31 @@ jobs:
           persist-credentials: false
           fetch-depth: 0
 
-      - name: Cache Node modules
-        uses: actions/cache@v3
-        with:
-          path: |
-            node_modules
-          key: npm-${{ hashFiles('package-lock.json') }}
-
       - name: Cache Gradle
         uses: burrunan/gradle-cache-action@v1
 
-      - name: Build with Gradle
+      - name: Build
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: ./gradlew build clean --no-daemon
+        run: ./gradlew build clean
 
-      - name: Setup semantic-release
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "lts/*"
+          cache: 'npm'
+
+      - name: Install dependencies
         run: npm install
 
+      - name: Import GPG key
+        uses: crazy-max/ghaction-import-gpg@v6
+        with:
+          gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}
+          passphrase: ${{ secrets.GPG_PASSPHRASE }}
+          fingerprint: ${{ vars.GPG_FINGERPRINT }}
+
       - name: Release
         env:
-          GITHUB_TOKEN: ${{ secrets.REPOSITORY_PUSH_ACCESS }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: npm exec semantic-release

.github/workflows/update_documentation.yml

@@ -0,0 +1,19 @@
+name: Update documentation
+
+on:
+  push:
+    paths:
+      - docs/**
+
+jobs:
+  trigger:
+    runs-on: ubuntu-latest
+    name: Dispatch event to documentation repository
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.DOCUMENTATION_REPO_ACCESS_TOKEN  }}
+          repository: revanced/revanced-documentation
+          event-type: update-documentation
+          client-payload: '{"repo": "${{ github.event.repository.name }}", "ref": "${{ github.ref }}"}'

.releaserc

@@ -23,7 +23,8 @@
         "assets": [
           "CHANGELOG.md",
           "gradle.properties"
-        ]
+        ],
+        "message": "chore: Release v${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
       }
     ],
     [

CHANGELOG.md

@@ -1,3 +1,194 @@
+## [20.0.2](https://github.com/ReVanced/revanced-patcher/compare/v20.0.1...v20.0.2) (2024-10-17)
+
+
+### Bug Fixes
+
+* Make it work on Android 12 and lower by using existing APIs ([#312](https://github.com/ReVanced/revanced-patcher/issues/312)) ([a44802e](https://github.com/ReVanced/revanced-patcher/commit/a44802ef4ebf59ae47213854ba761c81dadc51f3))
+
+## [20.0.2-dev.1](https://github.com/ReVanced/revanced-patcher/compare/v20.0.1...v20.0.2-dev.1) (2024-10-15)
+
+
+### Bug Fixes
+
+* Make it work on Android 12 and lower by using existing APIs ([#312](https://github.com/ReVanced/revanced-patcher/issues/312)) ([a44802e](https://github.com/ReVanced/revanced-patcher/commit/a44802ef4ebf59ae47213854ba761c81dadc51f3))
+
+## [20.0.1](https://github.com/ReVanced/revanced-patcher/compare/v20.0.0...v20.0.1) (2024-10-13)
+
+
+### Bug Fixes
+
+* Check for class type exactly instead of with contains ([#310](https://github.com/ReVanced/revanced-patcher/issues/310)) ([69f2f20](https://github.com/ReVanced/revanced-patcher/commit/69f2f20fd99162f91cd9c531dfe47d00d3152ead))
+* Make it work on Android by not using APIs from JVM unavailable to Android. ([2be6e97](https://github.com/ReVanced/revanced-patcher/commit/2be6e97817437f40e17893dfff3bea2cd4c3ff9e))
+* Use non-nullable type for options ([ea6fc70](https://github.com/ReVanced/revanced-patcher/commit/ea6fc70caab055251ad4d0d3f1b5cf53865abb85))
+
+
+### Performance Improvements
+
+* Free memory earlier and remove negligible lookup maps ([d53aacd](https://github.com/ReVanced/revanced-patcher/commit/d53aacdad4ed3750ddae526fb307577ea36e6171))
+
+## [20.0.1-dev.5](https://github.com/ReVanced/revanced-patcher/compare/v20.0.1-dev.4...v20.0.1-dev.5) (2024-10-11)
+
+
+### Bug Fixes
+
+* Use non-nullable type for options ([ea6fc70](https://github.com/ReVanced/revanced-patcher/commit/ea6fc70caab055251ad4d0d3f1b5cf53865abb85))
+
+## [20.0.1-dev.4](https://github.com/ReVanced/revanced-patcher/compare/v20.0.1-dev.3...v20.0.1-dev.4) (2024-10-07)
+
+
+### Bug Fixes
+
+* Make it work on Android by not using APIs from JVM unavailable to Android. ([2be6e97](https://github.com/ReVanced/revanced-patcher/commit/2be6e97817437f40e17893dfff3bea2cd4c3ff9e))
+
+## [20.0.1-dev.3](https://github.com/ReVanced/revanced-patcher/compare/v20.0.1-dev.2...v20.0.1-dev.3) (2024-10-03)
+
+
+### Performance Improvements
+
+* Free memory earlier and remove negligible lookup maps ([d53aacd](https://github.com/ReVanced/revanced-patcher/commit/d53aacdad4ed3750ddae526fb307577ea36e6171))
+
+## [20.0.1-dev.2](https://github.com/ReVanced/revanced-patcher/compare/v20.0.1-dev.1...v20.0.1-dev.2) (2024-10-01)
+
+## [20.0.1-dev.1](https://github.com/ReVanced/revanced-patcher/compare/v20.0.0...v20.0.1-dev.1) (2024-09-18)
+
+
+### Bug Fixes
+
+* Check for class type exactly instead of with contains ([#310](https://github.com/ReVanced/revanced-patcher/issues/310)) ([69f2f20](https://github.com/ReVanced/revanced-patcher/commit/69f2f20fd99162f91cd9c531dfe47d00d3152ead))
+
+# [20.0.0](https://github.com/ReVanced/revanced-patcher/compare/v19.3.1...v20.0.0) (2024-08-06)
+
+
+### Bug Fixes
+
+* Downgrade smali to fix dex compilation issue ([5227e98](https://github.com/ReVanced/revanced-patcher/commit/5227e98abfaa2ff1204eb20a0f2671f58c489930))
+* Improve exception message wording ([5481d0c](https://github.com/ReVanced/revanced-patcher/commit/5481d0c54ccecc91cd8d15af1ba2d3285a33e5ab))
+* Make constructor internal as supposed ([7f44174](https://github.com/ReVanced/revanced-patcher/commit/7f44174d91f0af0d50a83d80a7103c779241e094))
+* Merge all extensions before initializing lookup maps ([8c4dd5b](https://github.com/ReVanced/revanced-patcher/commit/8c4dd5b3a309077fa9a3827b4931fc28b0517809))
+* Use null for compatible package version when adding packages only ([736b3ee](https://github.com/ReVanced/revanced-patcher/commit/736b3eebbfdd7279b8d5fcfc5c46c9e3aadbee12))
+
+
+### Features
+
+* Add ability to create options outside of a patch ([d310246](https://github.com/ReVanced/revanced-patcher/commit/d310246852504b08a15f6376bbf25ac7c6fae76f))
+* Convert APIs to Kotlin DSL ([#298](https://github.com/ReVanced/revanced-patcher/issues/298)) ([11a911d](https://github.com/ReVanced/revanced-patcher/commit/11a911dc674eb0801649949dd3f28dfeb00efe97))
+
+
+### BREAKING CHANGES
+
+* Various old APIs are removed, and DSL APIs are added instead.
+
+# [20.0.0-dev.4](https://github.com/ReVanced/revanced-patcher/compare/v20.0.0-dev.3...v20.0.0-dev.4) (2024-08-06)
+
+
+### Bug Fixes
+
+* Improve exception message wording ([bd434ce](https://github.com/ReVanced/revanced-patcher/commit/bd434ceb3394d1d5292e8b94e5bfd6da0e4e9c72))
+
+# [20.0.0-dev.3](https://github.com/ReVanced/revanced-patcher/compare/v20.0.0-dev.2...v20.0.0-dev.3) (2024-08-01)
+
+
+### Bug Fixes
+
+* Make constructor internal as supposed ([e95fcd1](https://github.com/ReVanced/revanced-patcher/commit/e95fcd1c0b641164bbf0840ec7e562aeb3bacc3e))
+
+
+### Features
+
+* Add ability to create options outside of a patch ([b8d763a](https://github.com/ReVanced/revanced-patcher/commit/b8d763a66e0601627dd71c8c24247726aa300146))
+
+# [20.0.0-dev.2](https://github.com/ReVanced/revanced-patcher/compare/v20.0.0-dev.1...v20.0.0-dev.2) (2024-07-31)
+
+
+### Bug Fixes
+
+* Downgrade smali to fix dex compilation issue ([714447d](https://github.com/ReVanced/revanced-patcher/commit/714447de70096bf736e8e1d31c14bb5f24195070))
+* Merge all extensions before initializing lookup maps ([328aa87](https://github.com/ReVanced/revanced-patcher/commit/328aa876d8ed7826be3713754b6404195e9fe84b))
+* Use null for compatible package version when adding packages only ([a8e8fa4](https://github.com/ReVanced/revanced-patcher/commit/a8e8fa4093deb8cffbd7a582409f41867f6b568b))
+
+# [20.0.0-dev.1](https://github.com/ReVanced/revanced-patcher/compare/v19.3.1...v20.0.0-dev.1) (2024-07-22)
+
+
+### Features
+
+* Convert APIs to Kotlin DSL ([#298](https://github.com/ReVanced/revanced-patcher/issues/298)) ([3f9cbd2](https://github.com/ReVanced/revanced-patcher/commit/3f9cbd2408fa085690a062b357e11e42c51e7f8b))
+
+
+### BREAKING CHANGES
+
+* Various old APIs are removed, and DSL APIs are added instead.
+
+## [19.3.1](https://github.com/ReVanced/revanced-patcher/compare/v19.3.0...v19.3.1) (2024-02-14)
+
+## [19.3.1-dev.1](https://github.com/ReVanced/revanced-patcher/compare/v19.3.0...v19.3.1-dev.1) (2024-02-14)
+
+# [19.3.0](https://github.com/ReVanced/revanced-patcher/compare/v19.2.0...v19.3.0) (2024-02-14)
+
+
+### Bug Fixes
+
+* Use `Patch#toString` to get patch class name, when no name available ([c9a8260](https://github.com/ReVanced/revanced-patcher/commit/c9a82608f7f2d6b3e64c0c949ea5d9f76fa46165))
+
+
+### Features
+
+* Read and write arbitrary files in APK files ([f1d7217](https://github.com/ReVanced/revanced-patcher/commit/f1d72174956c42234664dce152a27e6854e347e2))
+
+# [19.3.0-dev.2](https://github.com/ReVanced/revanced-patcher/compare/v19.3.0-dev.1...v19.3.0-dev.2) (2024-02-13)
+
+# [19.3.0-dev.1](https://github.com/ReVanced/revanced-patcher/compare/v19.2.1-dev.1...v19.3.0-dev.1) (2024-02-13)
+
+
+### Features
+
+* Read and write arbitrary files in APK files ([f1d7217](https://github.com/ReVanced/revanced-patcher/commit/f1d72174956c42234664dce152a27e6854e347e2))
+
+## [19.2.1-dev.1](https://github.com/ReVanced/revanced-patcher/compare/v19.2.0...v19.2.1-dev.1) (2024-01-27)
+
+
+### Bug Fixes
+
+* Use `Patch#toString` to get patch class name, when no name available ([c9a8260](https://github.com/ReVanced/revanced-patcher/commit/c9a82608f7f2d6b3e64c0c949ea5d9f76fa46165))
+
+# [19.2.0](https://github.com/ReVanced/revanced-patcher/compare/v19.1.0...v19.2.0) (2023-12-28)
+
+
+### Bug Fixes
+
+* Accept `PatchSet` in `PatchesConsumer#acceptPatches` ([716825f](https://github.com/ReVanced/revanced-patcher/commit/716825f232bf1aab3a97723968562aa6dbdb20b1))
+
+
+### Features
+
+* Add `PatchExtensions#registerNewPatchOption` function to simplify instantiation and registration of patch options ([4a91845](https://github.com/ReVanced/revanced-patcher/commit/4a9184597be99cd458496cce0ee68994e6b8735c))
+
+# [19.2.0-dev.1](https://github.com/ReVanced/revanced-patcher/compare/v19.1.1-dev.1...v19.2.0-dev.1) (2023-12-22)
+
+
+### Features
+
+* Add `PatchExtensions#registerNewPatchOption` function to simplify instantiation and registration of patch options ([4a91845](https://github.com/ReVanced/revanced-patcher/commit/4a9184597be99cd458496cce0ee68994e6b8735c))
+
+## [19.1.1-dev.1](https://github.com/ReVanced/revanced-patcher/compare/v19.1.0...v19.1.1-dev.1) (2023-12-01)
+
+
+### Bug Fixes
+
+* Accept `PatchSet` in `PatchesConsumer#acceptPatches` ([716825f](https://github.com/ReVanced/revanced-patcher/commit/716825f232bf1aab3a97723968562aa6dbdb20b1))
+
+# [19.1.0](https://github.com/ReVanced/revanced-patcher/compare/v19.0.0...v19.1.0) (2023-12-01)
+
+
+### Features
+
+* Add constructor to initialize patches without annotations ([462fbe2](https://github.com/ReVanced/revanced-patcher/commit/462fbe2cadf56d8b0dde33319256021093bd39d5))
+* Retrieve annotations in super and interface classes ([7aeae93](https://github.com/ReVanced/revanced-patcher/commit/7aeae93f3d9a13e294fe1bdb2586f79908af60af))
+
+
+### Performance Improvements
+
+* Use a hash set for fast lookup ([f1de9b3](https://github.com/ReVanced/revanced-patcher/commit/f1de9b39eff1db44c00acd3e41902b3ec6124776))
+
 # [19.1.0-dev.1](https://github.com/ReVanced/revanced-patcher/compare/v19.0.0...v19.1.0-dev.1) (2023-11-29)
 
 

CONTRIBUTING.md

@@ -0,0 +1,99 @@
+<p align="center">
+  <picture>
+    <source
+      width="256px"
+      media="(prefers-color-scheme: dark)"
+      srcset="assets/revanced-headline/revanced-headline-vertical-dark.svg"
+    >
+    <img 
+      width="256px"
+      src="assets/revanced-headline/revanced-headline-vertical-light.svg"
+    >
+  </picture>
+  <br>
+  <a href="https://revanced.app/">
+     <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="assets/revanced-logo/revanced-logo.svg" />
+         <img height="24px" src="assets/revanced-logo/revanced-logo.svg" />
+     </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://github.com/ReVanced">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://i.ibb.co/dMMmCrW/Git-Hub-Mark.png" />
+           <img height="24px" src="https://i.ibb.co/9wV3HGF/Git-Hub-Mark-Light.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="http://revanced.app/discord">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032563-d4e084b7-244e-4358-af50-26bde6dd4996.png" />
+           <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032563-d4e084b7-244e-4358-af50-26bde6dd4996.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://reddit.com/r/revancedapp">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032351-9d9d5619-8ef7-470a-9eec-2744ece54553.png" />
+           <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032351-9d9d5619-8ef7-470a-9eec-2744ece54553.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://t.me/app_revanced">
+      <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032213-faf25ab8-0bc3-4a94-a730-b524c96df124.png" />
+         <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032213-faf25ab8-0bc3-4a94-a730-b524c96df124.png" />
+      </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://x.com/revancedapp">
+      <picture>
+         <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/93124920/270180600-7c1b38bf-889b-4d68-bd5e-b9d86f91421a.png">
+         <img height="24px" src="https://user-images.githubusercontent.com/93124920/270108715-d80743fa-b330-4809-b1e6-79fbdc60d09c.png" />
+      </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://www.youtube.com/@ReVanced">
+      <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032714-c51c7492-0666-44ac-99c2-f003a695ab50.png" />
+         <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032714-c51c7492-0666-44ac-99c2-f003a695ab50.png" />
+     </picture>
+   </a>
+   <br>
+   <br>
+   Continuing the legacy of Vanced
+</p>
+
+# 👋 Contribution guidelines
+
+This document describes how to contribute to ReVanced Patcher.
+
+## 📖 Resources to help you get started
+
+- The [documentation](https://github.com/ReVanced/revanced-patcher/tree/docs/docs) contains the fundamentals
+  of ReVanced Patcher and how to use ReVanced Patcher to create patches
+- [Our backlog](https://github.com/orgs/ReVanced/projects/12) is where we keep track of what we're working on
+- [Issues](https://github.com/ReVanced/revanced-patcher/issues) are where we keep track of bugs and feature requests
+
+## 🙏 Submitting a feature request
+
+Features can be requested by opening an issue using the
+[Feature request issue template](https://github.com/ReVanced/revanced-patcher/issues/new?assignees=&labels=Feature+request&projects=&template=feature_request.yml&title=feat%3A+).
+
+> **Note**
+> Requests can be accepted or rejected at the discretion of maintainers of ReVanced Patcher.
+> Good motivation has to be provided for a request to be accepted.
+
+## 🐞 Submitting a bug report
+
+If you encounter a bug while using ReVanced Patcher, open an issue using the
+[Bug report issue template](https://github.com/ReVanced/revanced-patcher/issues/new?assignees=&labels=Bug+report&projects=&template=bug_report.yml&title=bug%3A+).
+
+## 📝 How to contribute
+
+1. Before contributing, it is recommended to open an issue to discuss your change
+   with the maintainers of ReVanced Patcher. This will help you determine whether your change is acceptable
+   and whether it is worth your time to implement it
+2. Development happens on the `dev` branch. Fork the repository and create your branch from `dev`
+3. Commit your changes
+4. Submit a pull request to the `dev` branch of the repository and reference issues
+   that your pull request closes in the description of your pull request
+5. Our team will review your pull request and provide feedback. Once your pull request is approved,
+   it will be merged into the `dev` branch and will be included in the next release of ReVanced Patcher
+
+❤️ Thank you for considering contributing to ReVanced Patcher,  
+ReVanced

README.md

@@ -1,3 +1,125 @@
+<p align="center">
+  <picture>
+    <source
+      width="256px"
+      media="(prefers-color-scheme: dark)"
+      srcset="assets/revanced-headline/revanced-headline-vertical-dark.svg"
+    >
+    <img 
+      width="256px"
+      src="assets/revanced-headline/revanced-headline-vertical-light.svg"
+    >
+  </picture>
+  <br>
+  <a href="https://revanced.app/">
+     <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="assets/revanced-logo/revanced-logo.svg" />
+         <img height="24px" src="assets/revanced-logo/revanced-logo.svg" />
+     </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://github.com/ReVanced">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://i.ibb.co/dMMmCrW/Git-Hub-Mark.png" />
+           <img height="24px" src="https://i.ibb.co/9wV3HGF/Git-Hub-Mark-Light.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="http://revanced.app/discord">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032563-d4e084b7-244e-4358-af50-26bde6dd4996.png" />
+           <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032563-d4e084b7-244e-4358-af50-26bde6dd4996.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://reddit.com/r/revancedapp">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032351-9d9d5619-8ef7-470a-9eec-2744ece54553.png" />
+           <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032351-9d9d5619-8ef7-470a-9eec-2744ece54553.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://t.me/app_revanced">
+      <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032213-faf25ab8-0bc3-4a94-a730-b524c96df124.png" />
+         <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032213-faf25ab8-0bc3-4a94-a730-b524c96df124.png" />
+      </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://x.com/revancedapp">
+      <picture>
+         <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/93124920/270180600-7c1b38bf-889b-4d68-bd5e-b9d86f91421a.png">
+         <img height="24px" src="https://user-images.githubusercontent.com/93124920/270108715-d80743fa-b330-4809-b1e6-79fbdc60d09c.png" />
+      </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://www.youtube.com/@ReVanced">
+      <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032714-c51c7492-0666-44ac-99c2-f003a695ab50.png" />
+         <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032714-c51c7492-0666-44ac-99c2-f003a695ab50.png" />
+     </picture>
+   </a>
+   <br>
+   <br>
+   Continuing the legacy of Vanced
+</p>
+
 # 💉 ReVanced Patcher
 
+![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/ReVanced/revanced-patcher/release.yml)
+![GPLv3 License](https://img.shields.io/badge/License-GPL%20v3-yellow.svg)
+
 ReVanced Patcher used to patch Android applications.
+
+## ❓ About
+
+ReVanced Patcher is a library that is used to patch Android applications.  
+It powers [ReVanced Manager](https://github.com/ReVanced/revanced-manager),
+[ReVanced CLI](https://github.com/ReVanced/revanced-cli)
+and [ReVanced Library](https://github.com/ReVanced/revanced-library) and a rich set of patches have been developed
+using ReVanced Patcher in the [ReVanced Patches](https://github.com/ReVanced/revanced-patches) repository.
+
+## 💪 Features
+
+Some of the features the ReVanced Patcher provides are:
+
+- 🔧 **Patch Dalvik VM bytecode**: Disassemble and assemble Dalvik bytecode
+- 📦 **Patch APK resources**: Decode and build Android APK resources
+- 📂 **Patch arbitrary APK files**: Read and write arbitrary files directly from and to APK files
+- 🧩 **Write modular patches**: Extensive API to write modular patches that can patch Dalvik VM bytecode,
+APK resources and arbitrary APK files
+
+## 🚀 How to get started
+
+To use ReVanced Patcher in your project, follow these steps:
+
+1. [Add the repository](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry#using-a-published-package)
+to your project
+2. Add the dependency to your project:
+
+   ```kt
+    dependencies {
+        implementation("app.revanced:revanced-patcher:{$version}")
+    }
+   ```
+
+For a minimal project configuration, 
+see [ReVanced Patches template](https://github.com/ReVanced/revanced-patches-template).
+
+## 📚 Everything else
+
+### 📙 Contributing
+
+Thank you for considering contributing to ReVanced Patcher.
+You can find the contribution guidelines [here](CONTRIBUTING.md).
+
+### 🛠️ Building
+
+To build ReVanced Patcher,
+you can follow the [ReVanced documentation](https://github.com/ReVanced/revanced-documentation).
+
+### 📃 Documentation
+
+The documentation contains the fundamentals of ReVanced Patcher and how to use ReVanced Patcher to create patches.
+You can find it [here](https://github.com/ReVanced/revanced-patcher/tree/main/docs).
+
+## 📜 Licence
+
+ReVanced Patcher is licensed under the GPLv3 license. Please see the [licence file](LICENSE) for more information.
+[tl;dr](https://www.tldrlegal.com/license/gnu-general-public-license-v3-gpl-3) you may copy, distribute and modify ReVanced Patcher as long as you track changes/dates in source files.
+Any modifications to ReVanced Patcher must also be made available under the GPL,
+along with build & install instructions.

build.gradle.kts

@@ -1,9 +1,10 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
 plugins {
-    kotlin("jvm") version "1.9.10"
+    alias(libs.plugins.kotlin)
     alias(libs.plugins.binary.compatibility.validator)
     `maven-publish`
     signing
-    java
 }
 
 group = "app.revanced"
@@ -23,34 +24,59 @@ tasks {
 
 repositories {
     mavenCentral()
-    mavenLocal()
-    maven { url = uri("https://jitpack.io") }
     google()
+    maven {
+        // A repository must be specified for some reason. "registry" is a dummy.
+        url = uri("https://maven.pkg.github.com/revanced/registry")
+        credentials {
+            username = project.findProperty("gpr.user") as String? ?: System.getenv("GITHUB_ACTOR")
+            password = project.findProperty("gpr.key") as String? ?: System.getenv("GITHUB_TOKEN")
+        }
+    }
 }
 
 dependencies {
-    implementation(libs.kotlinx.coroutines.core)
-    implementation(libs.xpp3)
-    implementation(libs.smali)
-    implementation(libs.multidexlib2)
+    // TODO: Convert project to KMP.
+    compileOnly(libs.android) {
+        // Exclude, otherwise the org.w3c.dom API breaks.
+        exclude(group = "xerces", module = "xmlParserAPIs")
+    }
+
     implementation(libs.apktool.lib)
     implementation(libs.kotlin.reflect)
+    implementation(libs.kotlinx.coroutines.core)
+    implementation(libs.multidexlib2)
+    implementation(libs.smali)
+    implementation(libs.xpp3)
 
-    compileOnly(libs.android)
-
+    testImplementation(libs.mockk)
     testImplementation(libs.kotlin.test)
 }
 
+kotlin {
+    compilerOptions {
+        jvmTarget.set(JvmTarget.JVM_11)
+    }
+}
+
 java {
-    withJavadocJar()
+    targetCompatibility = JavaVersion.VERSION_11
+
     withSourcesJar()
 }
 
-kotlin {
-    jvmToolchain(11)
-}
-
 publishing {
+    repositories {
+        maven {
+            name = "GitHubPackages"
+            url = uri("https://maven.pkg.github.com/revanced/revanced-patcher")
+            credentials {
+                username = System.getenv("GITHUB_ACTOR")
+                password = System.getenv("GITHUB_TOKEN")
+            }
+        }
+    }
+
     publications {
         create<MavenPublication>("revanced-patcher-publication") {
             from(components["java"])
@@ -84,3 +110,8 @@ publishing {
         }
     }
 }
+
+signing {
+    useGpgCmd()
+    sign(publishing.publications["revanced-patcher-publication"])
+}

docs/1_patcher_intro.md

@@ -0,0 +1,111 @@
+<p align="center">
+  <picture>
+    <source
+      width="256px"
+      media="(prefers-color-scheme: dark)"
+      srcset="../assets/revanced-headline/revanced-headline-vertical-dark.svg"
+    >
+    <img 
+      width="256px"
+      src="../assets/revanced-headline/revanced-headline-vertical-light.svg"
+    >
+  </picture>
+  <br>
+  <a href="https://revanced.app/">
+     <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="../assets/revanced-logo/revanced-logo.svg" />
+         <img height="24px" src="../assets/revanced-logo/revanced-logo.svg" />
+     </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://github.com/ReVanced">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://i.ibb.co/dMMmCrW/Git-Hub-Mark.png" />
+           <img height="24px" src="https://i.ibb.co/9wV3HGF/Git-Hub-Mark-Light.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="http://revanced.app/discord">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032563-d4e084b7-244e-4358-af50-26bde6dd4996.png" />
+           <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032563-d4e084b7-244e-4358-af50-26bde6dd4996.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://reddit.com/r/revancedapp">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032351-9d9d5619-8ef7-470a-9eec-2744ece54553.png" />
+           <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032351-9d9d5619-8ef7-470a-9eec-2744ece54553.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://t.me/app_revanced">
+      <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032213-faf25ab8-0bc3-4a94-a730-b524c96df124.png" />
+         <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032213-faf25ab8-0bc3-4a94-a730-b524c96df124.png" />
+      </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://x.com/revancedapp">
+      <picture>
+         <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/93124920/270180600-7c1b38bf-889b-4d68-bd5e-b9d86f91421a.png">
+         <img height="24px" src="https://user-images.githubusercontent.com/93124920/270108715-d80743fa-b330-4809-b1e6-79fbdc60d09c.png" />
+      </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://www.youtube.com/@ReVanced">
+      <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032714-c51c7492-0666-44ac-99c2-f003a695ab50.png" />
+         <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032714-c51c7492-0666-44ac-99c2-f003a695ab50.png" />
+     </picture>
+   </a>
+   <br>
+   <br>
+   Continuing the legacy of Vanced
+</p>
+
+# 💉 Introduction to ReVanced Patcher
+
+To create patches for Android apps, it is recommended to know the basic concept of ReVanced Patcher.
+
+## 📙 How it works
+
+ReVanced Patcher is a library that allows modifying Android apps by applying patches.
+It is built on top of [Smali](https://github.com/google/smali) for bytecode manipulation and [Androlib (Apktool)](https://github.com/iBotPeaches/Apktool)
+for resource decoding and encoding.
+
+ReVanced Patcher receives a list of patches and applies them to a given APK file.
+It then returns the modified components of the APK file, such as modified dex files and resources,
+that can be repackaged into a new APK file.
+
+ReVanced Patcher has a simple API that allows you to load patches from RVP (JAR or DEX container) files
+and apply them to an APK file. Later on, you will learn how to create patches.
+
+```kt
+val patches = loadPatchesFromJar(setOf(File("revanced-patches.rvp")))
+
+val patcherResult = Patcher(PatcherConfig(apkFile = File("some.apk"))).use { patcher ->
+    // Here you can access metadata about the APK file through patcher.context.packageMetadata
+    // such as package name, version code, version name, etc.
+
+    // Add patches.
+    patcher += patches
+
+    // Execute the patches.
+    runBlocking {
+        patcher().collect { patchResult ->
+            if (patchResult.exception != null)
+                logger.info { "\"${patchResult.patch}\" failed:\n${patchResult.exception}" }
+            else
+                logger.info { "\"${patchResult.patch}\" succeeded" }
+        }
+    }
+
+    // Compile and save the patched APK file components.
+    patcher.get()
+}
+
+// The result of the patcher contains the modified components of the APK file that can be repackaged into a new APK file.
+val dexFiles = patcherResult.dexFiles
+val resources = patcherResult.resources
+```
+
+## ⏭️ What's next
+
+The next page teaches the fundamentals of ReVanced Patches.
+
+Continue: [🧩 Introduction to ReVanced Patches](2_patches_intro.md)

docs/2_1_setup.md

@@ -0,0 +1,112 @@
+<p align="center">
+  <picture>
+    <source
+      width="256px"
+      media="(prefers-color-scheme: dark)"
+      srcset="../assets/revanced-headline/revanced-headline-vertical-dark.svg"
+    >
+    <img 
+      width="256px"
+      src="../assets/revanced-headline/revanced-headline-vertical-light.svg"
+    >
+  </picture>
+  <br>
+  <a href="https://revanced.app/">
+     <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="../assets/revanced-logo/revanced-logo.svg" />
+         <img height="24px" src="../assets/revanced-logo/revanced-logo.svg" />
+     </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://github.com/ReVanced">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://i.ibb.co/dMMmCrW/Git-Hub-Mark.png" />
+           <img height="24px" src="https://i.ibb.co/9wV3HGF/Git-Hub-Mark-Light.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="http://revanced.app/discord">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032563-d4e084b7-244e-4358-af50-26bde6dd4996.png" />
+           <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032563-d4e084b7-244e-4358-af50-26bde6dd4996.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://reddit.com/r/revancedapp">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032351-9d9d5619-8ef7-470a-9eec-2744ece54553.png" />
+           <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032351-9d9d5619-8ef7-470a-9eec-2744ece54553.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://t.me/app_revanced">
+      <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032213-faf25ab8-0bc3-4a94-a730-b524c96df124.png" />
+         <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032213-faf25ab8-0bc3-4a94-a730-b524c96df124.png" />
+      </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://x.com/revancedapp">
+      <picture>
+         <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/93124920/270180600-7c1b38bf-889b-4d68-bd5e-b9d86f91421a.png">
+         <img height="24px" src="https://user-images.githubusercontent.com/93124920/270108715-d80743fa-b330-4809-b1e6-79fbdc60d09c.png" />
+      </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://www.youtube.com/@ReVanced">
+      <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032714-c51c7492-0666-44ac-99c2-f003a695ab50.png" />
+         <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032714-c51c7492-0666-44ac-99c2-f003a695ab50.png" />
+     </picture>
+   </a>
+   <br>
+   <br>
+   Continuing the legacy of Vanced
+</p>
+
+# 👶 Setting up a development environment
+
+To start developing patches with ReVanced Patcher, you must prepare a development environment.
+
+## 📝 Prerequisites
+
+- A Java IDE with Kotlin support, such as [IntelliJ IDEA](https://www.jetbrains.com/idea/)
+- Knowledge of Java, [Kotlin](https://kotlinlang.org), and [Dalvik bytecode](https://source.android.com/docs/core/runtime/dalvik-bytecode)
+- Android reverse engineering skills and tools such as [jadx](https://github.com/skylot/jadx)
+
+## 🏃 Prepare the environment
+
+Throughout the documentation, [ReVanced Patches](https://github.com/revanced/revanced-patches) will be used as an example project.
+
+> [!NOTE]
+> To start a fresh project, 
+> you can use the [ReVanced Patches template](https://github.com/revanced/revanced-patches-template).
+
+1. Clone the repository
+
+   ```bash
+   git clone https://github.com/revanced/revanced-patches && cd revanced-patches
+   ```
+
+2. Build the project
+
+   ```bash
+   ./gradlew build
+   ```
+
+> [!NOTE]
+> If the build fails due to authentication, you may need to authenticate to GitHub Packages.
+> Create a PAT with the scope `read:packages` [here](https://github.com/settings/tokens/new?scopes=read:packages&description=ReVanced) and add your token to ~/.gradle/gradle.properties.
+>
+> Example `gradle.properties` file:
+>
+> ```properties
+> gpr.user = user
+> gpr.key = key
+> ```
+
+3. Open the project in your IDE
+
+> [!TIP]
+> It is a good idea to set up a complete development environment for ReVanced, so that you can also test your patches
+> by following the [ReVanced documentation](https://github.com/ReVanced/revanced-documentation).
+
+## ⏭️ What's next
+
+The next page will go into details about a ReVanced patch.
+
+Continue: [🧩 Anatomy of a patch](2_2_patch_anatomy.md)

docs/2_patches_intro.md

@@ -0,0 +1,126 @@
+<p align="center">
+  <picture>
+    <source
+      width="256px"
+      media="(prefers-color-scheme: dark)"
+      srcset="../assets/revanced-headline/revanced-headline-vertical-dark.svg"
+    >
+    <img 
+      width="256px"
+      src="../assets/revanced-headline/revanced-headline-vertical-light.svg"
+    >
+  </picture>
+  <br>
+  <a href="https://revanced.app/">
+     <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="../assets/revanced-logo/revanced-logo.svg" />
+         <img height="24px" src="../assets/revanced-logo/revanced-logo.svg" />
+     </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://github.com/ReVanced">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://i.ibb.co/dMMmCrW/Git-Hub-Mark.png" />
+           <img height="24px" src="https://i.ibb.co/9wV3HGF/Git-Hub-Mark-Light.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="http://revanced.app/discord">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032563-d4e084b7-244e-4358-af50-26bde6dd4996.png" />
+           <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032563-d4e084b7-244e-4358-af50-26bde6dd4996.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://reddit.com/r/revancedapp">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032351-9d9d5619-8ef7-470a-9eec-2744ece54553.png" />
+           <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032351-9d9d5619-8ef7-470a-9eec-2744ece54553.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://t.me/app_revanced">
+      <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032213-faf25ab8-0bc3-4a94-a730-b524c96df124.png" />
+         <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032213-faf25ab8-0bc3-4a94-a730-b524c96df124.png" />
+      </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://x.com/revancedapp">
+      <picture>
+         <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/93124920/270180600-7c1b38bf-889b-4d68-bd5e-b9d86f91421a.png">
+         <img height="24px" src="https://user-images.githubusercontent.com/93124920/270108715-d80743fa-b330-4809-b1e6-79fbdc60d09c.png" />
+      </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://www.youtube.com/@ReVanced">
+      <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032714-c51c7492-0666-44ac-99c2-f003a695ab50.png" />
+         <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032714-c51c7492-0666-44ac-99c2-f003a695ab50.png" />
+     </picture>
+   </a>
+   <br>
+   <br>
+   Continuing the legacy of Vanced
+</p>
+
+# 🧩 Introduction to ReVanced Patches
+
+Learn the basic concepts of ReVanced Patcher and how to create patches.
+
+## 📙 Fundamentals
+
+A patch is a piece of code that modifies an Android application.  
+There are multiple types of patches. Each type can modify a different part of the APK, such as the Dalvik VM bytecode, 
+the APK resources, or arbitrary files in the APK:
+
+- A `BytecodePatch` modifies the Dalvik VM bytecode
+- A `ResourcePatch` modifies (decoded) resources
+- A `RawResourcePatch` modifies arbitrary files
+
+Each patch can declare a set of dependencies on other patches. ReVanced Patcher will first execute dependencies
+before executing the patch itself. This way, multiple patches can work together for abstract purposes in a modular way.
+
+The `execute` function is the entry point for a patch. It is called by ReVanced Patcher when the patch is executed.
+The `execute` function receives an instance of a context object that provides access to the APK.
+The patch can use this context to modify the APK.
+
+Each type of context provides different APIs to modify the APK. For example, the `BytecodePatchContext` provides APIs
+to modify the Dalvik VM bytecode, while the `ResourcePatchContext` provides APIs to modify resources.
+
+The difference between `ResourcePatch` and `RawResourcePatch` is that ReVanced Patcher will decode the resources
+if it is supplied a `ResourcePatch` for execution or if any patch depends on a `ResourcePatch`
+and will not decode the resources before executing `RawResourcePatch`.
+Both, `ResourcePatch` and `RawResourcePatch` can modify arbitrary files in the APK,
+whereas only `ResourcePatch` can modify decoded resources. The choice of which type to use depends on the use case.
+Decoding and building resources is a time- and resource-consuming,
+so if the patch does not need to modify decoded resources, it is better to use `RawResourcePatch` or `BytecodePatch`.
+
+Example of patches:
+
+```kt
+@Surpress("unused")
+val bytecodePatch = bytecodePatch {
+    execute { 
+        // More about this on the next page of the documentation.
+    }
+}
+
+@Surpress("unused")
+val rawResourcePatch = rawResourcePatch {
+    execute {
+        // More about this on the next page of the documentation.
+    }
+}
+
+@Surpress("unused")
+val resourcePatch = resourcePatch {
+    execute {
+        // More about this on the next page of the documentation.
+    }
+}
+```
+
+> [!TIP]
+> To see real-world examples of patches,
+> check out the repository for [ReVanced Patches](https://github.com/revanced/revanced-patches).
+
+## ⏭️ Whats next
+
+The next page will guide you through creating a development environment for creating patches.
+
+Continue: [👶 Setting up a development environment](2_1_setup.md)

docs/3_structure_and_conventions.md

@@ -0,0 +1,105 @@
+<p align="center">
+  <picture>
+    <source
+      width="256px"
+      media="(prefers-color-scheme: dark)"
+      srcset="../assets/revanced-headline/revanced-headline-vertical-dark.svg"
+    >
+    <img 
+      width="256px"
+      src="../assets/revanced-headline/revanced-headline-vertical-light.svg"
+    >
+  </picture>
+  <br>
+  <a href="https://revanced.app/">
+     <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="../assets/revanced-logo/revanced-logo.svg" />
+         <img height="24px" src="../assets/revanced-logo/revanced-logo.svg" />
+     </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://github.com/ReVanced">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://i.ibb.co/dMMmCrW/Git-Hub-Mark.png" />
+           <img height="24px" src="https://i.ibb.co/9wV3HGF/Git-Hub-Mark-Light.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="http://revanced.app/discord">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032563-d4e084b7-244e-4358-af50-26bde6dd4996.png" />
+           <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032563-d4e084b7-244e-4358-af50-26bde6dd4996.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://reddit.com/r/revancedapp">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032351-9d9d5619-8ef7-470a-9eec-2744ece54553.png" />
+           <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032351-9d9d5619-8ef7-470a-9eec-2744ece54553.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://t.me/app_revanced">
+      <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032213-faf25ab8-0bc3-4a94-a730-b524c96df124.png" />
+         <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032213-faf25ab8-0bc3-4a94-a730-b524c96df124.png" />
+      </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://x.com/revancedapp">
+      <picture>
+         <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/93124920/270180600-7c1b38bf-889b-4d68-bd5e-b9d86f91421a.png">
+         <img height="24px" src="https://user-images.githubusercontent.com/93124920/270108715-d80743fa-b330-4809-b1e6-79fbdc60d09c.png" />
+      </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://www.youtube.com/@ReVanced">
+      <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032714-c51c7492-0666-44ac-99c2-f003a695ab50.png" />
+         <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032714-c51c7492-0666-44ac-99c2-f003a695ab50.png" />
+     </picture>
+   </a>
+   <br>
+   <br>
+   Continuing the legacy of Vanced
+</p>
+
+# 📜 Project structure and conventions
+
+Over time, a specific project structure and conventions have been established.
+
+## 📁 File structure
+
+Patches are organized in a specific way. The file structure looks as follows:
+
+```text
+📦your.patches.app.category
+ ├ 🔍Fingerprints.kt
+ └ 🧩SomePatch.kt
+```
+
+> [!NOTE]
+> Moving fingerprints to a separate file isn't strictly necessary, but it helps the organization when a patch uses multiple fingerprints.
+
+## 📙 Conventions
+
+- 🔥 Name a patch after what it does. For example, if a patch removes ads, name it `Remove ads`.
+  If a patch changes the color of a button, name it `Change button color`
+- 🔥 Write the patch description in the third person, present tense, and end it with a period.
+  If a patch removes ads, the description can be omitted because of redundancy,
+  but if a patch changes the color of a button, the description can be _Changes the color of the resume button to red._
+- 🔥 Write patches with modularity and reusability in mind. Patches can depend on each other,
+  so it is important to write patches in a way that can be used in different contexts.
+- 🔥🔥 Keep patches as minimal as possible. This reduces the risk of failing patches.
+  Instead of involving many abstract changes in one patch or writing entire methods or classes in a patch,
+  you can write code in extensions. An extension is a precompiled DEX file that is merged into the patched app 
+  before this patch is executed.
+  Patches can then reference methods and classes from extensions.
+  A real-world example of extensions can be found in the [ReVanced Patches](https://github.com/ReVanced/revanced-patches) repository
+- 🔥🔥🔥 Do not overload a fingerprint with information about a method that's likely to change.
+  In the example of an obfuscated method, it's better to fingerprint the method by its return type
+  and parameters rather than its name because the name is likely to change. An intelligent selection
+  of an opcode pattern or strings in a method can result in a strong fingerprint dynamic to app updates.
+- 🔥🔥🔥 Document your patches. Patches are abstract, so it is important to document parts of the code
+  that are not self-explanatory. For example, explain why and how a certain method is patched or large blocks
+  of instructions that are modified or added to a method
+
+## ⏭️ What's next
+
+The next page discusses useful APIs for patch development.
+
+Continue: [💪 Advanced APIs](4_apis.md)

docs/4_apis.md

@@ -0,0 +1,25 @@
+# 💪 Advanced APIs
+
+A handful of APIs are available to make patch development easier and more efficient.
+
+## 📙 Overview
+
+1. 👹 Create mutable replacements of classes with `proxy(ClassDef)`
+2. 🔍 Find and create mutable replaces with `classBy(Predicate)`
+3. 🏃‍ Navigate method calls recursively by index with `navigate(Method).at(index)`
+4. 💾 Read and write resource files with `get(Path, Boolean)`
+5. 📃 Read and write DOM files using `document`
+
+### 🧰 APIs
+
+> [!WARNING]
+> This section is still under construction and may be incomplete.
+
+## 🎉 Afterword
+
+ReVanced Patcher is a powerful library to patch Android applications, offering a rich set of APIs to develop patches
+that outlive app updates. Patches make up ReVanced; without you, the community of patch developers,
+ReVanced would not be what it is today. We hope that this documentation has been helpful to you
+and are excited to see what you will create with ReVanced Patcher. If you have any questions or need help,
+talk to us on one of our platforms linked on [revanced.app](https://revanced.app) or open an issue in case of a bug or feature request,  
+ReVanced

docs/README.md

@@ -0,0 +1,73 @@
+<p align="center">
+  <picture>
+    <source
+      width="256px"
+      media="(prefers-color-scheme: dark)"
+      srcset="../assets/revanced-headline/revanced-headline-vertical-dark.svg"
+    >
+    <img 
+      width="256px"
+      src="../assets/revanced-headline/revanced-headline-vertical-light.svg"
+    >
+  </picture>
+  <br>
+  <a href="https://revanced.app/">
+     <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="../assets/revanced-logo/revanced-logo.svg" />
+         <img height="24px" src="../assets/revanced-logo/revanced-logo.svg" />
+     </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://github.com/ReVanced">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://i.ibb.co/dMMmCrW/Git-Hub-Mark.png" />
+           <img height="24px" src="https://i.ibb.co/9wV3HGF/Git-Hub-Mark-Light.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="http://revanced.app/discord">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032563-d4e084b7-244e-4358-af50-26bde6dd4996.png" />
+           <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032563-d4e084b7-244e-4358-af50-26bde6dd4996.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://reddit.com/r/revancedapp">
+       <picture>
+           <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032351-9d9d5619-8ef7-470a-9eec-2744ece54553.png" />
+           <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032351-9d9d5619-8ef7-470a-9eec-2744ece54553.png" />
+       </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://t.me/app_revanced">
+      <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032213-faf25ab8-0bc3-4a94-a730-b524c96df124.png" />
+         <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032213-faf25ab8-0bc3-4a94-a730-b524c96df124.png" />
+      </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://x.com/revancedapp">
+      <picture>
+         <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/93124920/270180600-7c1b38bf-889b-4d68-bd5e-b9d86f91421a.png">
+         <img height="24px" src="https://user-images.githubusercontent.com/93124920/270108715-d80743fa-b330-4809-b1e6-79fbdc60d09c.png" />
+      </picture>
+   </a>&nbsp;&nbsp;&nbsp;
+   <a href="https://www.youtube.com/@ReVanced">
+      <picture>
+         <source height="24px" media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/13122796/178032714-c51c7492-0666-44ac-99c2-f003a695ab50.png" />
+         <img height="24px" src="https://user-images.githubusercontent.com/13122796/178032714-c51c7492-0666-44ac-99c2-f003a695ab50.png" />
+     </picture>
+   </a>
+   <br>
+   <br>
+   Continuing the legacy of Vanced
+</p>
+
+# 💉 Documentation of ReVanced Patcher
+
+This documentation contains the fundamentals of ReVanced Patcher and how to use ReVanced Patcher to create patches
+
+## 📖 Table of content
+
+1. [💉 Introduction to ReVanced Patcher](1_patcher_intro.md)
+2. [🧩 Introduction to ReVanced Patches](2_patches_intro.md)
+   1. [👶 Setting up a development environment](2_1_setup.md)
+   2. [🧩 Anatomy of a ReVanced patch](2_2_patch_anatomy.md)
+      1. [🔎 Fingerprinting](2_2_1_fingerprinting.md)
+   3. [📜 Project structure and conventions](3_structure_and_conventions.md)
+   4. [💪 Advanced APIs](4_apis.md)

gradle.properties

@@ -1,4 +1,3 @@
 org.gradle.parallel = true
 org.gradle.caching = true
-kotlin.code.style = official
-version = 19.1.0-dev.1
+version = 20.0.2

gradle/libs.versions.toml

@@ -1,23 +1,27 @@
 [versions]
 android = "4.1.1.4"
-kotlin-reflect = "1.9.10"
-apktool-lib = "2.9.1"
-kotlin-test = "1.9.10"
-kotlinx-coroutines-core = "1.7.3"
+apktool-lib = "2.9.3"
+binary-compatibility-validator = "0.15.1"
+kotlin = "2.0.0"
+kotlinx-coroutines-core = "1.8.1"
+mockk = "1.13.10"
 multidexlib2 = "3.0.3.r3"
-smali = "3.0.3"
+# Tracking https://github.com/google/smali/issues/64.
+#noinspection GradleDependency
+smali = "3.0.5"
 xpp3 = "1.1.4c"
-binary-compatibility-validator = "0.13.2"
 
 [libraries]
 android = { module = "com.google.android:android", version.ref = "android" }
-kotlin-reflect = { module = "org.jetbrains.kotlin:kotlin-reflect", version.ref = "kotlin-reflect" }
-apktool-lib = { module = "app.revanced:apktool", version.ref = "apktool-lib" }
-kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test", version.ref = "kotlin-test" }
+apktool-lib = { module = "app.revanced:apktool-lib", version.ref = "apktool-lib" }
+kotlin-reflect = { module = "org.jetbrains.kotlin:kotlin-reflect", version.ref = "kotlin" }
 kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "kotlinx-coroutines-core" }
+kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test", version.ref = "kotlin" }
+mockk = { module = "io.mockk:mockk", version.ref = "mockk" }
 multidexlib2 = { module = "app.revanced:multidexlib2", version.ref = "multidexlib2" }
 smali = { module = "com.android.tools.smali:smali", version.ref = "smali" }
 xpp3 = { module = "xpp3:xpp3", version.ref = "xpp3" }
 
 [plugins]
 binary-compatibility-validator = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version.ref = "binary-compatibility-validator" }
+kotlin = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,8 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip
-distributionSha256Sum=3e1af3ae886920c3ac87f7a91f816c0c7c436f276a6eefdb3da152100fef72ae
+distributionSha256Sum=d725d707bfabd4dfdc958c624003b3c80accc03f7037b5122c4b1d0ef15cecab
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME
-zipStorePath=wrapper/dist
+zipStorePath=wrapper/dists

gradlew

@@ -15,6 +15,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+# SPDX-License-Identifier: Apache-2.0
+#
 
 ##############################################################################
 #
@@ -55,7 +57,7 @@
 #       Darwin, MinGW, and NonStop.
 #
 #   (3) This script is generated from the Groovy template
-#       https://github.com/gradle/gradle/blob/HEAD/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
 #       within the Gradle project.
 #
 #       You can find Gradle at https://github.com/gradle/gradle/.
@@ -83,7 +85,9 @@ done
 # This is normally unused
 # shellcheck disable=SC2034
 APP_BASE_NAME=${0##*/}
-APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s
+' "$PWD" ) || exit
 
 # Use the maximum available, or set MAX_FD != -1 to use that value.
 MAX_FD=maximum
@@ -144,7 +148,7 @@ if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
     case $MAX_FD in #(
       max*)
         # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
-        # shellcheck disable=SC3045
+        # shellcheck disable=SC2039,SC3045
         MAX_FD=$( ulimit -H -n ) ||
             warn "Could not query maximum file descriptor limit"
     esac
@@ -152,7 +156,7 @@ if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
       '' | soft) :;; #(
       *)
         # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
-        # shellcheck disable=SC3045
+        # shellcheck disable=SC2039,SC3045
         ulimit -n "$MAX_FD" ||
             warn "Could not set maximum file descriptor limit to $MAX_FD"
     esac
@@ -201,11 +205,11 @@ fi
 # Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
 DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
 
-# Collect all arguments for the java command;
-#   * $DEFAULT_JVM_OPTS, $JAVA_OPTS, and $GRADLE_OPTS can contain fragments of
-#     shell script including quotes and variable substitutions, so put them in
-#     double quotes to make sure that they get re-expanded; and
-#   * put everything else in single quotes, so that it's not re-expanded.
+# Collect all arguments for the java command:
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+#     and any embedded shellness will be escaped.
+#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+#     treated as '${Hostname}' itself on the command line.
 
 set -- \
         "-Dorg.gradle.appname=$APP_BASE_NAME" \

gradlew.bat

@@ -13,6 +13,8 @@
 @rem See the License for the specific language governing permissions and
 @rem limitations under the License.
 @rem
+@rem SPDX-License-Identifier: Apache-2.0
+@rem
 
 @if "%DEBUG%"=="" @echo off
 @rem ##########################################################################
@@ -43,11 +45,11 @@ set JAVA_EXE=java.exe
 %JAVA_EXE% -version >NUL 2>&1
 if %ERRORLEVEL% equ 0 goto execute
 
-echo.
-echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
-echo.
-echo Please set the JAVA_HOME variable in your environment to match the
-echo location of your Java installation.
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
 
 goto fail
 
@@ -57,11 +59,11 @@ set JAVA_EXE=%JAVA_HOME%/bin/java.exe
 
 if exist "%JAVA_EXE%" goto execute
 
-echo.
-echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
-echo.
-echo Please set the JAVA_HOME variable in your environment to match the
-echo location of your Java installation.
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
 
 goto fail
 

package.json

@@ -1,9 +1,9 @@
 {
   "devDependencies": {
-    "@saithodev/semantic-release-backmerge": "^3.2.1",
+    "@saithodev/semantic-release-backmerge": "^4.0.1",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
-    "gradle-semantic-release-plugin": "^1.8.0",
-    "semantic-release": "^22.0.8"
+    "gradle-semantic-release-plugin": "^1.10.1",
+    "semantic-release": "^24.1.2"
   }
 }

settings.gradle.kts

@@ -1,7 +1 @@
 rootProject.name = "revanced-patcher"
-
-buildCache {
-    local {
-        isEnabled = !System.getenv().containsKey("CI")
-    }
-}