How to Add New Package Recommendations to Universal Android Debloater: Complete Contribution Guidelines

Open an issue using the "Add new package(s)" template, create a branch named with the issue number, edit resources/assets/uad_lists.json following the schema, verify with cargo run -p uad-cli -- update, and submit a PR using the package addition template.

The Universal Android Debloater Next Generation (UAD-ng) manages its package recommendations through a centralized JSON database. Contributing new entries requires following a specific workflow defined in the repository's contribution guidelines to ensure data integrity and traceability. This guide covers the complete process from issue creation to merge, referencing the actual source files and validation scripts used by the project.

Open an Issue Using the Official Template

The contribution workflow begins with the "Add new package(s)" issue template. This template can be accessed directly via the repository's issue creation URL with the add-new-package.yml parameter.

Filling out the template requires specific package details including the package name, category, safety rating, and description. Upon submission, the issue automatically receives the package::addition label, which signals to maintainers that this issue tracks a new package submission. According to the CONTRIBUTING.md file lines 75-78, this labeling system is essential for routing submissions to the correct review workflow.

Create a Branch Following the Naming Convention

UAD-ng uses a trunk-based development model with short-lived feature branches. For package additions, the branch name must include the issue number and a descriptive title.

For example, if your issue is #1234, create your branch like this:

git checkout -b 1234-add-youtube-ads-package

The branch naming rules are documented in the Branching strategy section of CONTRIBUTING.md (lines 52-55). This convention ensures that every commit can be traced back to its originating issue.

Edit the Package List in uad_lists.json

The package database resides at resources/assets/uad_lists.json. Each entry must conform to a strict JSON schema used by the Rust core.

Package Schema Structure

Each package entry requires the following fields:

• package: The Android package name (e.g., com.example.app)
• category: Classification such as adware, bloatware, or analytics
• safe: Boolean indicating whether removal is safe (true/false)
• description: Concise explanation under 200 characters describing user-visible impact
• why: Required when safe is false, explaining why disabling the package is safe despite the flag

An example entry looks like this:

{
  "package": "com.example.app",
  "category": "adware",
  "safe": false,
  "description": "Shows intrusive ads on the lock screen.",
  "why": "This is a standalone advertising package with no system dependencies."
}

Contribution Guidelines for Data Quality

When editing uad_lists.json, follow these validation rules from the contribution guidelines (lines 71-78 in CONTRIBUTING.md):

• Verify the package does not already exist in the database
• Test on a real device or emulator to confirm the described behavior
• Keep descriptions factual and under 200 characters
• Include the why field for any package marked as unsafe
• Use a conventional commit message format: feat(package): add [package name]

Reference the issue in your commit message using Closes #1234 to enable automatic issue closure on merge.

Practical Editing Example

When adding a new package, use jq to safely modify the JSON without syntax errors:

jq '. + [{
  "package": "com.example.ads",
  "category": "adware",
  "safe": false,
  "description": "Displays persistent ads on the lock screen.",
  "why": "Standalone advertising module with no system dependencies."
}]' resources/assets/uad_lists.json > tmp.json && mv tmp.json resources/assets/uad_lists.json

Then commit with the conventional format:

git add resources/assets/uad_lists.json
git commit -m "feat(package): add example ads package

Closes #5678"

Validate Changes Locally with the CLI

Before submitting, verify that your JSON edits are syntactically correct and compatible with the Rust parser. The project includes a validation command that reads uad_lists.json via the core library.

Run the update command from the repository root:

cargo run -p uad-cli -- update

This command invokes the update sub-command defined in crates/uad-cli/src/commands.rs. The parser loads the JSON using the include_str! macro in crates/uad-core/src/uad_lists.rs (lines 12-19), where LIST_FNAME defines the file path. If the JSON contains syntax errors or schema violations, the CLI exits with an error, providing early feedback before you open a pull request.

Submit a Pull Request Using the Package Template

Push your branch to your fork and open a pull request against the main branch. Select the "Package addition" PR template located at .github/PULL_REQUEST_TEMPLATE/packages.md.

This template contains a mandatory checklist that enforces the contribution guidelines, including verification that you tested on a device, checked for duplicates, and followed the schema requirements (lines 9-20).

When the PR is merged, the CI workflow defined in .github/workflows/ci.yml automatically runs the test suite, which includes a sanity check of uad_lists.json. The uad update CI job then publishes the updated list to the repository assets, making new recommendations available to downstream users automatically.

Summary

• Open an issue using the "Add new package(s)" template to receive the package::addition label
• Create branches using the format [issue-number]-[brief-description] per the trunk-based development model
• Edit resources/assets/uad_lists.json following the strict schema with fields for package, category, safe, description, and conditional why
• Validate JSON syntax using cargo run -p uad-cli -- update before submitting
• Use conventional commits referencing the issue number (e.g., feat(package): add Example App\n\nCloses #1234)
• Submit PRs using the package addition template at .github/PULL_REQUEST_TEMPLATE/packages.md

Frequently Asked Questions

What file contains the package recommendations in UAD-ng?

The package recommendations are stored in resources/assets/uad_lists.json. This file is compiled into the application using the include_str! macro in crates/uad-core/src/uad_lists.rs, allowing the Rust code to access the data at compile time through the LIST_FNAME constant.

Do I need to build the entire project to validate my JSON changes?

No, you only need to run the CLI validation command. Execute cargo run -p uad-cli -- update from the repository root to verify that your edits to uad_lists.json are syntactically correct and parseable by the core library. This command checks the JSON against the expected schema without requiring a full build of the GUI components.

What should I include in the commit message for new packages?

Use conventional commit format starting with feat(package): followed by a brief description of the addition. Include the issue reference using Closes #1234 (replacing with your actual issue number) in the commit body to ensure the issue automatically closes when the PR merges. This format is required per the contribution guidelines in CONTRIBUTING.md.

How do I indicate that a package is unsafe to remove but should still be listed?

Set the safe field to false and include the required why field explaining the rationale. The why field should clarify why disabling the package is considered safe despite the safe: false flag, such as noting that the package is a standalone advertising module with no system dependencies. This two-field approach allows the debloater to warn users while providing context for the safety rating.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}