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

> Learn how to add new package recommendations to Universal Android Debloater. Follow our contribution guidelines to submit your package lists and improve the debloater for everyone.

- Repository: [Universal-Debloater-Alliance/universal-android-debloater-next-generation](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation)
- Tags: how-to-guide
- Published: 2026-06-20

---

**Open an issue using the "Add new package(s)" template, create a branch named with the issue number, edit [`resources/assets/uad_lists.json`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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:

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

```

The branch naming rules are documented in the **Branching strategy** section of [`CONTRIBUTING.md`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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:

```json
{
  "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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/uad_lists.json), follow these validation rules from the contribution guidelines (lines 71-78 in [`CONTRIBUTING.md`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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:

```bash
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:

```bash
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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/uad_lists.json) via the core library.

Run the update command from the repository root:

```bash
cargo run -p uad-cli -- update

```

This command invokes the `update` sub-command defined in [`crates/uad-cli/src/commands.rs`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/crates/uad-cli/src/commands.rs). The parser loads the JSON using the `include_str!` macro in [`crates/uad-core/src/uad_lists.rs`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/.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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/.github/workflows/ci.yml) automatically runs the test suite, which includes a sanity check of [`uad_lists.json`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/.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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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`](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/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.