# Version information is documented or accessible

- **Pattern:** `ab-001954` (`mobile-store-readiness.version-management.version-documented`)
- **Severity:** info
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-001954
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-001954)

## Why it matters

Version history documentation serves two concrete functions: it lets users understand what changed in an update before installing (reducing negative reviews from unexpected behavior changes), and it gives future maintainers a reliable source of truth for which version introduced which behavior. App stores surface "What's New" text in update prompts — an empty or generic "Bug fixes and improvements" entry significantly reduces update adoption rates, which matters for security patches that need broad uptake. ISO 25010:2011 maintainability quality attributes include changeability and testability, both of which depend on accurate version documentation. Without a CHANGELOG, diagnosing regressions across version boundaries requires git archaeology instead of a changelog lookup.

## Severity rationale

Info because missing version documentation doesn't cause rejection but measurably reduces update adoption and increases future maintenance cost for regression triage.

## Remediation

Create `CHANGELOG.md` at the project root using Keep a Changelog format and tag releases in git to link the changelog to deployable artifacts.

```markdown
# Changelog

## [1.1.0] - 2026-03-15
### Added
- Push notifications for order status updates
- Dark mode support

### Fixed
- Login timeout on slow connections

## [1.0.0] - 2026-02-01
- Initial release
```

```bash
# Tag each release in git
git tag -a v1.1.0 -m "Order notifications + dark mode"
git push origin v1.1.0
```

Paste a condensed version of the current section into the App Store Connect "What's New" field and Google Play Console release notes field at submission time. Keep notes user-facing ("Fixed login timeout") not implementation-focused ("Refactored auth token refresh logic").

## Detection

- **ID:** `version-documented`
- **Severity:** `info`
- **What to look for:** Check for a CHANGELOG.md or similar version history file. Count the number of version entries documented. Look for version tags in git or release notes in the app store listing. Verify that current app version (`app.json` `version` field) is documented with release notes explaining what changed.
- **Pass criteria:** A CHANGELOG or release notes exist documenting the current version and what changed. At least 1 version entry must be present with at least 2 bullet points describing changes. Version is referenced consistently between app.json and documentation.
- **Fail criteria:** No changelog or release notes found, or current version is undocumented. Changelog exists but has fewer than 2 entries or descriptions.
- **Skip (N/A) when:** First release of the app (changelog can start with this version).
- **Detail on fail:** `"No CHANGELOG.md found"` or `"Current version 1.1.0 is not documented in release notes"`
- **Remediation:** Document version changes to help users and future developers. Create:
  1. CHANGELOG.md:
     ```markdown
     # Changelog

     ## [1.0.0] - 2026-02-21
     - Initial release
     - User authentication
     - Core features

     ## [1.0.1] - 2026-03-01
     - Fixed login bug
     - Improved performance
     ```
  2. Tag releases in git:
     ```bash
     git tag -a v1.0.0 -m "Initial release"
     git push origin v1.0.0
     ```
  3. Add release notes to app store:
     - App Store Connect: Release Notes field in app info
     - Google Play Console: Release notes field in release section
  4. Keep notes concise and user-focused (what changed, not technical details)

## External references

- iso-25010 maintainability

Taxons: code-quality

HTML version: https://auditbuffet.com/patterns/ab-001954