# Termux package publication specification

[`PRODUCT.md`](PRODUCT.md) incorporates this document as normative version 1 distribution behavior.
This document governs publication to the official
[`termux/termux-packages`](https://github.com/termux/termux-packages) repositories.
It does not grant this project authority over Termux infrastructure or maintainer decisions.

The upstream contribution rules are external policy and may change. Before each submission, the
publisher must re-read the current packaging policy, contribution guide, and package build
instructions. The requirements below fail closed when they conflict with current upstream policy.

## Ownership boundary

This repository owns source releases and release evidence.
The official `termux/termux-packages` repository owns the accepted package recipe, package revision,
build infrastructure, signing, repository metadata, mirrors, and deployment.

This project never stores Termux signing keys, repository-upload credentials, or an unofficial
binary package under an official name. A source release, local `.deb`, fork branch, or pull request
is not a deployment. Publication is complete only after official infrastructure serves the package.

## Package identity and contents

The requested package name is `termux-janitor` in the main repository under
`packages/termux-janitor/build.sh`, unless Termux maintainers require another supported location.
The package installs exactly:

- `$PREFIX/bin/termux-janitor`;
- the manual page required by [`MAN_PAGE.md`](MAN_PAGE.md);
- license material required by upstream policy.

The recipe adds no service, daemon, shell startup edit, scheduled task, privileged component,
post-install mutation, telemetry, or default configuration file. Runtime dependencies are derived
from the final binary and behavior, never copied from build dependencies.

The installed binary must not self-update or bypass `pkg` and `apt`. Upgrades and removal remain
owned by the Termux package manager.

## Upstream release input

A publishable upstream release satisfies TJ-ART-01 through TJ-ART-12 in
[`REQUIREMENTS.md`](REQUIREMENTS.md) and has passing repository release gates from an unmodified
checkout.

The package recipe fetches the official release input by immutable version and verifies its digest.
It builds from source with the Zig version pinned by this repository and accepted by current Termux
build policy. It never fetches a prebuilt `termux-janitor` binary or a moving branch.

## Recipe requirements

The recipe follows the current upstream `build.sh` contract and declares homepage, description,
SPDX license, maintainer, version, source URL, SHA-256 digest, and actual runtime dependencies.
Common Termux build tools are not runtime dependencies.

The build uses Termux-provided prefix, target, compiler, linker, flags, and staging directories.
It does not hard-code `/usr`, `/bin`, `/etc`, `/tmp`, the application sandbox path, one CPU
architecture, the publisher's home, or a build-host path. Necessary patches are minimal, separately
named, and submitted upstream to this project when they describe general Termux support.

The normal official architecture matrix is attempted. An architecture may be excluded only when a
Termux maintainer accepts the restriction. Package metadata, release evidence, and user-facing
limitations identify every exclusion. One successful architecture never implies support for another.

The resulting package must remain below the current upstream size limit. The publisher records
installed size and compressed package size for each attempted architecture.

## Submission workflow

For a new package:

1. Confirm the project satisfies current Termux packaging policy, including activity, open-source
   licensing, usefulness, non-duplication, and size requirements.
2. Finish and verify the upstream release input.
3. Create one focused recipe in a current fork of `termux/termux-packages`.
4. Build it with the current official package builder for every locally available target.
5. Run upstream formatting, lint, metadata, and package checks without bypasses.
6. Install the produced package into an isolated Termux test environment and execute the acceptance
   checks below.
7. Submit a focused pull request using the current contribution template and an `addpkg` commit
   subject accepted by upstream policy.
8. Record review-requested changes and rerun every invalidated check after rebasing.

For an existing package, update the immutable source version and digest, remove an obsolete package
revision, refresh patches, and use the current upstream `bump` convention. A recipe-only rebuild at
the same upstream version increments the package revision instead of changing source identity.

Only Termux maintainers merge and deploy. This project must not automate around review, required CI,
maintainer approval, or repository signing.

## Package acceptance

Before submission, and again for the exact accepted recipe when available, verify:

- the payload contains only declared package-owned paths, and installation or removal has no
  undeclared maintainer-script effect;
- `termux-janitor --help` and `--version` succeed without configuration or terminal setup;
- `man termux-janitor` resolves and renders without diagnostics;
- startup in an 80 by 24 terminal reaches the interactive UI;
- `--dry-run` cannot request package or direct-filesystem mutation beyond its run log;
- default configuration paths resolve within the installing Termux environment;
- the executable contains no build-host paths and resolves only declared runtime libraries;
- package-manager upgrade and removal leave no undeclared persistent state;
- required repository tests pass on each supported architecture;
- architecture, Android, terminal, filesystem, and package-manager limitations are recorded.

Tests use disposable homes and XDG directories. They never scan or mutate the publisher's real home,
package database, shared storage, or repositories.

## Deployment verification

After upstream merge, record the accepted commit and wait for official build and repository jobs.
For each published architecture, verify official repository metadata identifies the expected source
version and package revision. Install from an official mirror in a fresh Termux environment, rerun
the non-destructive package acceptance checks, and record the mirror and observation time.

A merged recipe without published artifacts is `accepted`, not `deployed`. A repository artifact
that cannot be installed and verified is `published-unverified`, not complete.

## Failure and correction

A failed source gate, checksum mismatch, unexplained binary difference, undeclared dependency,
unsupported architecture, unsafe installation effect, or missing manual page blocks submission.
A failed upstream CI job is fixed or the pull request is withdrawn; it is never skipped.

After deployment, report packaging defects to Termux maintainers and product defects to this
project. Corrections use a new upstream release or an incremented Termux package revision according
to which
owner changed. Existing official artifacts are never overwritten in place. A severe safety defect
requires requesting package disablement while a corrected immutable release is prepared.

## External policy evidence

This specification was checked on 2026-09-13 against:

- the Termux Packages contribution guide:
  [`CONTRIBUTING.md`](https://github.com/termux/termux-packages/blob/master/CONTRIBUTING.md),
  including packaging policy, source identity, dependency, recipe, update, and revision rules;
- [`termux-packages/README.md`](https://github.com/termux/termux-packages/blob/master/README.md),
  identifying the official build repository and current developer documentation.

These links are evidence, not frozen authority. A publication record includes the exact upstream
commit reviewed so later policy drift is detectable.