diff --git a/CODEOWNERS b/CODEOWNERS index 1d008d50f4..85b82ef838 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -1,7 +1,7 @@ * @duckduckgo/content-scope-scripts-owners # Documentation - anyone can edit -injected/docs/ * +injected/docs/ # Feature owners injected/src/features/fingerprinting-* @duckduckgo/content-scope-scripts-owners @jonathanKingston @englehardt diff --git a/injected/docs/README.md b/injected/docs/README.md index ebe7a0e78d..802032362d 100644 --- a/injected/docs/README.md +++ b/injected/docs/README.md @@ -9,6 +9,7 @@ This directory contains detailed documentation for the Content Scope Scripts pro - **[API Reference](./api-reference.md)** - Complete reference for the Content Scope Features API - **[Features Guide](./features-guide.md)** - How to develop features and understand the feature lifecycle - **[Platform Integration](./platform-integration.md)** - Platform-specific implementation details and integration patterns +- **[Platform-Specific Build & Troubleshooting Tips](./build-and-troubleshooting.md)** - Troubleshooting and setup tips for iOS, macOS, Android, Windows, and Extensions ### Development Resources @@ -25,7 +26,7 @@ This directory contains detailed documentation for the Content Scope Scripts pro If you're new to Content Scope Scripts, start with the main [README](../README.md) for a high-level overview, then dive into the specific documentation based on your needs: - **Building features?** → [Features Guide](./features-guide.md) -- **Integrating with a platform?** → [Platform Integration](./platform-integration.md) +- **Integrating with a platform?** → [Platform Integration](./platform-integration.md) and [Platform-Specific Build & Troubleshooting Tips](./build-and-troubleshooting.md) - **Using the API?** → [API Reference](./api-reference.md) - **Developing utilities?** → [Development Utilities](./development-utilities.md) - **Testing your changes?** → [Testing Guide](./testing-guide.md) diff --git a/injected/docs/build-and-troubleshooting.md b/injected/docs/build-and-troubleshooting.md new file mode 100644 index 0000000000..7ff4a32661 --- /dev/null +++ b/injected/docs/build-and-troubleshooting.md @@ -0,0 +1,49 @@ +# Platform-Specific Build & Troubleshooting Tips + +This document provides platform-specific build instructions, troubleshooting steps, and local development tips for integrating and working with Content Scope Scripts (C-S-S) across iOS, macOS, Android, Windows, and browser extensions. + +--- + +## iOS/macOS + +- **Check Xcode Version:** + - [.xcode-version](https://github.com/duckduckgo/apple-browsers/tree/main/.xcode-version) +- **Set up C-S-S or Autofill as a Local Dependency:** + - Drag the folder from Finder into the directory panel in Xcode. +- **Privacy Config Files:** + - Both apps bundle a privacy config file: [macos-config.json](https://github.com/duckduckgo/apple-browsers/blob/main/macOS/DuckDuckGo/ContentBlocker/macos-config.json) & [ios-config.json](https://github.com/duckduckgo/apple-browsers/blob/main/iOS/Core/ios-config.json). + - To test privacy config changes, update this file as well as the config endpoint for remote updates ([macOS](https://github.com/duckduckgo/apple-browsers/blob/main/macOS/DuckDuckGo/Application/AppConfigurationURLProvider.swift#L60) & [iOS](https://github.com/duckduckgo/apple-browsers/blob/main/iOS/Core/AppURLs.swift#L49)). +- **If you receive errors related to packages:** + - File > Packages > Reset Package Caches + - Clean Project with `cmd+K` + - Delete all files inside `~/Library/Developer/Xcode/DerivedData` + - If none of that works, ask for help in the [Apple Devs Mattermost channel](https://chat.duckduckgo.com/ddg/channels/devs). + +## Android + +- [Override the Privacy Remote Config](https://app.asana.com/1/137249556945/project/1202561462274611/task/1203855276415003?focus=true) + - Ensure the config version is higher than the current version (the app may refuse to update otherwise). +- **Clean Project:** + - Build → 'Clean Project' (clears cache of potentially stale C-S-S file). + - Uninstall the app from the emulator as well. +- **Linking Local Dependencies:** + - Use `npm link @duckduckgo/content-scope-scripts` or `npm link @duckduckgo/autofill` to link to your local checkout. + - In that directory, also run `npm link` in the dependency folder. + - This symlinks to your local dir and acts as if you're pointing to your PR. + - Run `npm build` in C-S-S (not run automatically like in the extension). +- **Alternative Android Setup (more reliable):** + - Alter the path of the resources in the appropriate module's `build.gradle` to an absolute path on your machine. + - Example: [build.gradle gist](https://gist.github.com/shakyShane/0b133a0782bdb37c876c4a4204667bb2) + - After making this change, click 'sync now' when Gradle prompts. + - All changes in C-S-S will be picked up every time you restart the app. + - This works for all JS dependencies (Autofill, Dashboard, C-S-S, etc). + +## Windows + +- [Work with content-scope-scripts repo on Windows](./development-utilities.md#windows-development) +- [Debugging `autofill.js` (or other submodules) on Windows](https://app.asana.com/1/137249556945/project/1198964220583541/task/1208938714611510) + +## Extensions + +- Use npm link as per Android. +- See the [other development steps](https://github.com/duckduckgo/duckduckgo-privacy-extension/blob/main/CONTRIBUTING.md#building-the-extension). diff --git a/injected/docs/platform-integration.md b/injected/docs/platform-integration.md index 5c648adb2b..cf18c71e1a 100644 --- a/injected/docs/platform-integration.md +++ b/injected/docs/platform-integration.md @@ -119,3 +119,5 @@ Check that relevant Privacy Features are working as expected: - **Cookie protection**: - [Block Third Party Tracking Cookies Implementation Guidelines](https://app.asana.com/1/137249556945/project/1198207348643509/task/1200539099112751?focus=true) - [Expire First Party Script Cookies Implementation Guidelines](https://app.asana.com/1/137249556945/project/1198207348643509/task/1200364574828671?focus=true) + +See [Platform-Specific Build & Troubleshooting Tips](./build-and-troubleshooting.md) for detailed troubleshooting and setup instructions.