From 06753373e5417f5d2b5395b446570c7354ad8efa Mon Sep 17 00:00:00 2001 From: Simon Hamp Date: Tue, 12 May 2026 18:16:49 +0100 Subject: [PATCH] Mobile v3 docs: simplify versioning guidance around NATIVEPHP_APP_VERSION - Remove NATIVEPHP_APP_VERSION/_CODE from the pre-install .env block; they default to DEBUG and aren't required up front. - Reframe the configuration page section: lead with what these vars actually are (public version string vs. internal build number, with iOS/Android mappings), note DEBUG is the default, and point at `native:release`. Move the bundled-Laravel extraction mechanics into an aside. - Update the deployment Releasing section to drive readers to `native:release` instead of editing .env by hand, recommend semver for version numbers, and clarify that the build number is auto-incremented and persisted by the command. Co-Authored-By: Claude Opus 4.7 (1M context) --- package-lock.json | 2 +- .../mobile/3/getting-started/configuration.md | 38 ++++++++++++------- .../mobile/3/getting-started/deployment.md | 21 +++++----- .../mobile/3/getting-started/installation.md | 4 +- 4 files changed, 38 insertions(+), 27 deletions(-) diff --git a/package-lock.json b/package-lock.json index 33750f8f..d3e89b39 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,5 +1,5 @@ { - "name": "jovial-camel", + "name": "noble-lynx", "lockfileVersion": 3, "requires": true, "packages": { diff --git a/resources/views/docs/mobile/3/getting-started/configuration.md b/resources/views/docs/mobile/3/getting-started/configuration.md index 6481e0b5..3674f056 100644 --- a/resources/views/docs/mobile/3/getting-started/configuration.md +++ b/resources/views/docs/mobile/3/getting-started/configuration.md @@ -34,27 +34,37 @@ So it's not something you want to be changing very often. ## `NATIVEPHP_APP_VERSION` -The `NATIVEPHP_APP_VERSION` environment variable controls your app's versioning behavior. +The `NATIVEPHP_APP_VERSION` environment variable sets your app's **public version string** - what shows up in App Store +and Play Store listings, and on-device under "Settings → Apps" (or equivalent). It maps to `CFBundleShortVersionString` +on iOS and `versionName` on Android. -When your app is compiling, NativePHP first copies the relevant Laravel files into a temporary directory, zips them up, -and embeds the archive into the native application. +Its companion, `NATIVEPHP_APP_VERSION_CODE`, sets the **internal build number** the stores use to distinguish uploads +(`CFBundleVersion` on iOS, `versionCode` on Android). Users don't normally see this one, but the stores require it to +increase with every upload. -When your app boots, it checks the embedded version against the previously installed version to see if it needs to -extract the bundled Laravel application. +`NATIVEPHP_APP_VERSION` defaults to `DEBUG`, which is what you want during development - every boot picks up your +latest code without needing to bump a version number by hand. -If the versions match, the app uses the existing files without re-extracting the archive. +You only need to change this when you're cutting a release build for distribution. Rather than editing your `.env` +manually, use the +[`native:release` command](/docs/mobile/3/getting-started/commands#nativerelease), which bumps the version (and build +number) for you. -To force your application to always install the latest version of your code - especially useful during development - -set this to `DEBUG`: + ## Persistent Runtime diff --git a/resources/views/docs/mobile/3/getting-started/deployment.md b/resources/views/docs/mobile/3/getting-started/deployment.md index f12891a4..b5742691 100644 --- a/resources/views/docs/mobile/3/getting-started/deployment.md +++ b/resources/views/docs/mobile/3/getting-started/deployment.md @@ -58,29 +58,32 @@ If you want more hands-on support, we happily work with our [Partners](/partners ## Releasing -To prepare your app for release, you should set the version number to a new version number that you have not used -before and increment the build number: +To prepare your app for release, bump the version number using the +[`native:release` command](/docs/mobile/3/getting-started/commands#nativerelease): -```dotenv -NATIVEPHP_APP_VERSION=1.2.3 -NATIVEPHP_APP_VERSION_CODE=48 +```shell +php artisan native:release patch ``` +You can pass `patch`, `minor`, or `major` depending on the type of release you're cutting. This updates +`NATIVEPHP_APP_VERSION` in your `.env` and increments the build number for you. + ### Versioning -You have complete freedom in how you version your applications. You may use semantic versioning, codenames, -date-based versions, or any scheme that works for your project, team or business. +App version numbers should follow [semantic versioning](https://semver.org) (e.g. `1.2.3`). The `native:release` command +relies on this format to determine how to bump your version. Remember that your app versions are usually public-facing (e.g. in store listings and on-device settings and update screens) and can be useful for customers to reference if they need to contact you for help and support. -The build number is managed via the `NATIVEPHP_APP_VERSION` key in your `.env`. +The app version is managed via the `NATIVEPHP_APP_VERSION` key in your `.env`. ### Build numbers Both the Google Play Store and Apple App Store require your app's build number to increase for each release you submit. -The build number is managed via the `NATIVEPHP_APP_VERSION_CODE` key in your `.env`. +The build number is managed via the `NATIVEPHP_APP_VERSION_CODE` key in your `.env`. You don't need to manage this +yourself — running `native:release` automatically increments the build number and persists it back to your `.env`. ### Run a `release` build diff --git a/resources/views/docs/mobile/3/getting-started/installation.md b/resources/views/docs/mobile/3/getting-started/installation.md index e2e91aac..ae602ec2 100644 --- a/resources/views/docs/mobile/3/getting-started/installation.md +++ b/resources/views/docs/mobile/3/getting-started/installation.md @@ -35,11 +35,9 @@ NativePHP does not work in WSL (Windows Subsystem for Linux). You must install a ```dotenv NATIVEPHP_APP_ID=com.yourcompany.yourapp -NATIVEPHP_APP_VERSION="DEBUG" -NATIVEPHP_APP_VERSION_CODE="1" ``` -Find out more about these options in +Find out more about this option in [Configuration](/docs/getting-started/configuration#codenativephp-app-idcode).