Repository navigation
docs assets app tutorial CAPTURE_CONTRACT
This contract links three things that must stay equal:
- an Android screen (Compose sources and string resources in
app/), - its tutorial capture in
docs/assets/app-tutorial/<feature>/NN-*.png, - every page or field of the public site (
landing/) that shows that capture or quotes a label from it.
When an app screen changes, the affected captures are taken again on the
emulator under the same conditions as before, and the site page or field that
uses them is updated in the same delivery. manifest.json is the
machine-readable side of this contract and
scripts/app_tutorial/tutorial_contract.py
enforces it.
| ID | Rule |
|---|---|
| C1 | Every PNG in this folder is listed once in manifest.json with a caption, the string resources it shows (strings), any extra sources (extraSources), the derived Compose sources, its sha256 and its context (city, account, notes). Numbers run 01..NN per feature without gaps. validate fails otherwise. |
| C2 | A change to a source file, to a listed string (any locale) or to a drawable used by a source makes the step stale. The change that makes it stale, or at the latest the next landing update, recaptures the step under the frozen conditions (C4) and runs refresh for it. Purely internal changes that leave the screen pixel-identical may be re-baselined with refresh after a visual comparison; say so in the PR. |
| C3 | The site never hot-links these masters. Derivatives keep the stem: <feature>-<NN-slug>-<width>w.webp (for example forum-05-write-comment-720w.webp). Site text that names an app control quotes the current pt-BR string exactly (for example "Rota e ir"). This is how stale finds the image uses and the quoted labels to update. |
| C4 | Capture conditions are frozen in manifest.json → capture and applied by scripts/app_tutorial/emulator.py setup. Changing a condition (device profile, size, density, locale, theme, status bar, cities, data week) means recapturing every step. |
| C5 | Privacy: synthetic emulator locations only, public ANP records only, a throwaway username-only account deleted at the end, nothing submitted to the community, forum, ratings or corrections (drafts only), no photos of people or plates, no OCR training images. FLAG_SECURE screens are never captured or bypassed; they are described in textOnlySteps. |
| C6 | Captures run on an emulator only. emulator.py refuses any serial that is not emulator-*; never use a contributor's or the owner's phone. |
| C7 | Text-only steps (textOnlySteps) follow the same staleness rule through their sources; update their wording when those screens change. |
| Item | Value |
|---|---|
| App | Debug build (./gradlew :app:assembleDebug), package com.anpfuel.app.debug, default API origin https://abastevo.com.br
|
| AVD |
abastevo-tutorial-api36: system-images;android-36;google_apis;x86_64, device pixel_7, 3072 MB RAM, hw.keyboard=yes
|
| Display |
wm size 1080x1920, wm density 420, light theme |
| Locale | system pt-BR (root setprop persist.sys.locale), app pt-BR (cmd locale set-app-locales), time zone America/Sao_Paulo
|
| Status bar | System UI demo mode: 10:00, battery 100 %, Wi-Fi 4 bars, mobile and notifications hidden |
| Network | emulator Wi-Fi AndroidWifi, mobile data off (map packs are Wi-Fi only) |
| Input | Gboard disabled and stylus handwriting off so no keyboard covers the screen; text typed with adb shell input text
|
| Cities | São Paulo, SP (fixes at -23.5505, -46.6333) and Sorriso, MT (-12.545, -55.711); map, route and navigation use Sorriso |
| Data | ANP week 8–14 Nov 2026 active; 1–7 Nov, 18–24 Oct and 4–10 Oct downloaded in the app for history |
| Synthetic user data | vehicle "Meu carro", 50 L, gasoline, cheapest station, price-drop alert on; one fuel-log entry (40 L, R$ 250,00, 12 500 km); favourite "Posto Dallas" |
| Output | opaque RGB PNG 1080 × 1920, then optipng -o2 -strip all (lossless) |
-
Find what is stale.
python3 scripts/app_tutorial/tutorial_contract.py stale
The report lists each stale image, why (source, string or drawable), the landing files that show it and the landing lines that quote a changed pt-BR label, with the old and new text. Use
--head <rev>to compare a commit and--jsonfor tooling. -
Build the app from the commit being documented, in a clean worktree (system Java is a JRE; use the cached JDK 17):
JAVA_HOME=~/.gradle/jdks/eclipse_adoptium-17-amd64-linux.2 ./gradlew :app:assembleDebug --offline -
Start the tutorial emulator. Create the AVD once, outside the repository, then boot it headless:
avdmanager create avd -n abastevo-tutorial-api36 -k "system-images;android-36;google_apis;x86_64" -d pixel_7emulator -avd abastevo-tutorial-api36 -port 5590 -no-window -no-audio -no-boot-anim -no-snapshot-save -gpu swiftshader_indirect -memory 3072
-
Apply the frozen conditions and install.
ANDROID_SERIAL=emulator-5590 python3 scripts/app_tutorial/emulator.py setup
adb -s emulator-5590 install -r app/build/outputs/apk/debug/app-debug.apk
Restart the emulator framework once after the first
setupso the system locale applies (adb -s emulator-5590 shell 'stop; start'), then runsetupagain. -
Reproduce the state named in the step's
context: city (emulator.py gps sorriso-mtand pick the city in the app), signed-in or guest, the active week and the synthetic data above. Navigate to the screen exactly as the caption says. -
Capture with the same file name:
ANDROID_SERIAL=emulator-5590 python3 scripts/app_tutorial/emulator.py shot docs/assets/app-tutorial/map/05-route-preview.png
A black capture fails: the screen is
FLAG_SECUREand becomes a text-only step. Then optimise losslessly:optipng -quiet -o2 -strip all docs/assets/app-tutorial/map/05-route-preview.png
-
Update the manifest. Record the new hash and the commit the build came from; when a caption, string list or step order changes, edit
manifest.jsonfirst, then:python3 scripts/app_tutorial/tutorial_contract.py refresh map/05-route-preview.png --commit HEAD
python3 scripts/app_tutorial/tutorial_contract.py sync-sources --write
python3 scripts/app_tutorial/tutorial_contract.py render-readme --write
python3 scripts/app_tutorial/tutorial_contract.py validate
-
Update the site. For every
landing image usein the stale report, regenerate the derivative from the new master (same stem, rule C3) with the parameters recorded inlanding/static/assets/app/provenance.json, and update its entry and theimageSha256of thelesson.jsonsteps that show it. For everylanding textline, replace the old label with the new pt-BR string. For steps with no current landing use, review thelandingTargetspages. Then run the landing checks:cd landing && npm ci && npm run typecheck && npm test && npm run build
-
Reset the emulator and deliver the app change, the recaptures, the manifest and the landing update in one pull request:
ANDROID_SERIAL=emulator-5590 python3 scripts/app_tutorial/emulator.py reset
scripts/quick-verify.sh runs the contract tests and validate (blocking) and
prints the stale report (informational; it skips when the clone has no
history back to the capture commit). Before publishing a landing update, run
stale --strict: it exits 1 while any step is stale.
- Home
- Roadmap
- docs-README
- docs-android-build
- docs-android-design-system
- docs-android-forum
- docs-android-games
- docs-android-map-engine
- docs-android-navigation
- docs-android-ocr-image
- docs-android-ocr-live-framing
- docs-android-premium-area
- docs-android-premium-integration
- docs-android-release
- docs-android-ui-containers
- docs-architecture-android-stack
- docs-architecture-android
- docs-architecture-backend
- docs-architecture-data-sources
- docs-architecture-overview
- docs-architecture-sources-ev-research
- docs-architecture-sources-national-limits
- docs-architecture-sources-national-stations
- docs-architecture-sources-register
- docs-assets-app-tutorial-CAPTURE_CONTRACT
- docs-assets-app-tutorial-FABLE_LANDING_POLISH_PROMPT
- docs-assets-app-tutorial-README
- docs-assets-attribution
- docs-assets-brand-README
- docs-assets-flags-ATTRIBUTION
- docs-assets-fuel-icons-README
- docs-assets-games-fuel-v1-README
- docs-assets-home-icons-README
- docs-assets-landing-fleet-android-20261012-BRIEF
- docs-assets-landing-hero-20261011-BRIEF
- docs-assets-landing-illustrated-20261012-BRIEF
- docs-assets-landing-illustrated-20261012-README
- docs-assets-landing-minimal-20261012-BRIEF
- docs-assets-landing-open-data-20261026-BRIEF
- docs-assets-landing-redesign-20261011-PREPARATION_EVIDENCE
- docs-assets-landing-redesign-20261011-README
- docs-assets-landing-redesign-20261011-REFERENCE_BRIEF
- docs-assets-landing-sync-20261012-BRIEF
- docs-assets-map-icons-README
- docs-backend-anp-ingestion
- docs-backend-api
- docs-backend-community-pricing
- docs-backend-data-model
- docs-backend-domain-model
- docs-backend-driver-private-data
- docs-backend-forum-architecture
- docs-backend-forum-bulletins
- docs-backend-forum-sources
- docs-backend-payments-provider-admission
- docs-backend-payments-provider-register
- docs-backend-photos-capture
- docs-backend-photos-subset-submission
- docs-backend-premium-api
- docs-backend-premium-cloud-protocol
- docs-backend-testing
- docs-backend-toolchain
- docs-brand-app-icons
- docs-brand-identity
- docs-decisions-001-kotlin-compose-stack
- docs-decisions-002-price-import-immutability
- docs-decisions-003-nominatim-reverse-geocode
- docs-decisions-005-modular-monolith-and-postgresql
- docs-decisions-006-official-catalog-and-exact-contracts
- docs-decisions-007-anonymous-proof-of-possession
- docs-decisions-008-privacy-and-retention
- docs-decisions-009-community-consensus-and-projections
- docs-decisions-010-private-object-evidence
- docs-decisions-012-licensing-and-hosted-business
- docs-decisions-015-kotlin-multiplatform-shared-domain
- docs-decisions-016-android-commercial-community-ios-deferred
- docs-decisions-017-station-profile-and-verified-representation
- docs-decisions-021-community-first-contribution
- docs-decisions-022-comaps-derived-native-map-engine
- docs-decisions-023-admin-suite-granted-tiers-contributors
- docs-decisions-025-private-abastevo-empresas-organization-boundary
- docs-decisions-026-multilingual-public-site
- docs-decisions-README
- docs-enterprise-README
- docs-enterprise-architecture
- docs-enterprise-backlog-INDEX
- docs-enterprise-backlog-ep00-governance
- docs-enterprise-backlog-ep01-platform
- docs-enterprise-backlog-ep02-organizations
- docs-enterprise-backlog-ep03-identity-access
- docs-enterprise-backlog-ep04-sync
- docs-enterprise-backlog-ep05-fleet-meters
- docs-enterprise-backlog-ep06-trips
- docs-enterprise-backlog-ep07-gps-navigation
- docs-enterprise-backlog-ep08-fuelings
- docs-enterprise-backlog-ep09-documents
- docs-enterprise-backlog-ep10-expenses-finance
- docs-enterprise-backlog-ep11-maintenance
- docs-enterprise-backlog-ep12-fuel-stock
- docs-enterprise-backlog-ep13-intelligence
- docs-enterprise-backlog-ep14-station-claims
- docs-enterprise-backlog-ep15-station-commerce
- docs-enterprise-backlog-ep16-subscriptions
- docs-enterprise-backlog-ep17-data
- docs-enterprise-backlog-ep18-imports-notifications-integrations
- docs-enterprise-backlog-ep19-back-office
- docs-enterprise-backlog-ep20-release
- docs-enterprise-business-rules
- docs-enterprise-contract
- docs-enterprise-conventions
- docs-enterprise-data-offering
- docs-enterprise-decisions
- docs-enterprise-domain-model
- docs-enterprise-glossary
- docs-enterprise-journeys
- docs-enterprise-modules-back-office
- docs-enterprise-modules-data
- docs-enterprise-modules-documents
- docs-enterprise-modules-expenses-finance
- docs-enterprise-modules-fleet
- docs-enterprise-modules-fuel-stock
- docs-enterprise-modules-fuelings
- docs-enterprise-modules-gps-navigation
- docs-enterprise-modules-identity
- docs-enterprise-modules-imports-notifications-integrations
- docs-enterprise-modules-intelligence
- docs-enterprise-modules-maintenance
- docs-enterprise-modules-organizations
- docs-enterprise-modules-station-claims
- docs-enterprise-modules-station-commerce
- docs-enterprise-modules-subscriptions
- docs-enterprise-modules-trips
- docs-enterprise-offline-sync
- docs-enterprise-permissions
- docs-enterprise-portal-routes
- docs-enterprise-privacy-security
- docs-enterprise-product-vision
- docs-enterprise-source-admission
- docs-enterprise-state-model
- docs-enterprise-testing
- docs-enterprise-ux-app
- docs-enterprise-ux-web
- docs-operations-README
- docs-operations-backup
- docs-operations-deploy-agent
- docs-operations-dou-editions
- docs-operations-edge-cache
- docs-operations-enterprise-activation
- docs-operations-map-static-overlay
- docs-operations-moderation-feedback
- docs-operations-moderation-profiles
- docs-operations-monitoring
- docs-operations-operator-access
- docs-operations-payments
- docs-operations-premium-billing
- docs-operations-recovery
- docs-operations-registry-daily-sync
- docs-operations-registry-runs
- docs-product-README
- docs-product-admin-tiers
- docs-product-community-community-first
- docs-product-community-experience
- docs-product-community-metrics
- docs-product-community-moderation
- docs-product-community-safety
- docs-product-community-terms-pt-br
- docs-product-driver-suite-README
- docs-product-driver-suite-android-state
- docs-product-driver-suite-cloud-sync
- docs-product-driver-suite-cost-profiles-and-maintenance
- docs-product-driver-suite-driver-model-and-earnings
- docs-product-driver-suite-foundation-decisions
- docs-product-driver-suite-gps-lifecycle
- docs-product-driver-suite-mobile-hub
- docs-product-driver-suite-odometer-review
- docs-product-driver-suite-outbox-wire
- docs-product-driver-suite-quick-refuel
- docs-product-driver-suite-reports
- docs-product-driver-suite-shifts-and-distance
- docs-product-driver-suite-signed-commands
- docs-product-ev-README
- docs-product-ev-charging-stop-planner
- docs-product-ev-energy-model
- docs-product-ev-financial-method
- docs-product-ev-journey-ui
- docs-product-ev-preparation
- docs-product-ev-typed-data
- docs-product-exploration
- docs-product-forum-contract
- docs-product-forum-policies
- docs-product-glossary
- docs-product-landing-content
- docs-product-landing-guides
- docs-product-landing-organic-growth-i18n-plan
- docs-product-licensing
- docs-product-map-discovery
- docs-product-map-favorites-and-trips
- docs-product-map-reports-routing-guidance
- docs-product-notification-content
- docs-product-official-prices
- docs-product-open-source-business
- docs-product-overview
- docs-product-payments-README
- docs-product-payments-offer-policy
- docs-product-premium-README
- docs-product-premium-financial-method
- docs-product-premium-source-policy
- docs-product-stations-catalog
- docs-product-stations-fuel-feedback
- docs-product-stations-fuel-quality
- docs-product-stations-identity-and-ev-catalog
- docs-product-stations-profile-contract
- docs-product-stations-profile-representation
- docs-product-stations-registry-sources
- docs-product-vehicle-registration
- docs-product-vehicles-and-occurrences
- docs-security-android-terms-acceptance
- docs-security-free-account-access
- docs-security-identity-profile
- docs-security-media-location-policy
- docs-security-privacy-notice
- docs-security-privacy-policy
- docs-security-retention
- docs-security-risks
- docs-security-security-privacy
- docs-store-README
- docs-store-play-readiness
- docs-store-play-store-listing
- docs-store-ugc-safety
Source: AlexandreZanata/Abastevo @ e4a67580fc368a59bc1c0f1e0466fc011313f330