Skip to content

release-process.md

Latest commit

 

History

History
195 lines (132 loc) · 6.16 KB

release-process.md

File metadata and controls

195 lines (132 loc) · 6.16 KB
Raw

Release Process

The release process for IntroVox covers version management, build, GitHub release, and App Store upload. For the authoritative per-release checklist see RELEASE_CHECKLIST.md in the repository root.

Versioning

IntroVox follows Semantic Versioning:

  • MAJOR — breaking API or storage-format changes
  • MINOR — backwards-compatible features
  • PATCH — backwards-compatible bug fixes

Version Synchronization

Two files declare the IntroVox version and must stay in sync:

File Field
package.json version
appinfo/info.xml <version>

Verify they match before every release:

grep '"version"' package.json
grep '<version>' appinfo/info.xml

Release Flow

1. Prepare

# Verify versions match
grep version package.json appinfo/info.xml

# Production build
npm run build

# Regenerate translations if l10n/*.json changed
python3 regenerate_js_translations.py

2. Update the CHANGELOG

Add a new section at the top of CHANGELOG.md following the existing pattern:

## [X.Y.Z] - YYYY-MM-DD

### Added
- New feature (#NUMBER)

### Changed
- Behavior change

### Fixed
- Bug fix (#NUMBER)

### Security
- Security improvement

Every entry that maps to a GitHub issue should include a markdown link to that issue — e.g. ([#16](https://github.com/nextcloud/IntroVox/issues/16)).

3. Commit and Push

git add -A
git commit -m "Release vX.Y.Z - [Description]"
git push gitea main
git push github main

4. Tag and Push the Tag

git tag -a vX.Y.Z -m "Release vX.Y.Z - [Description]"
git push gitea vX.Y.Z
git push github vX.Y.Z

5. Build the Tarball

The tarball's root folder must be introvox (lowercase, no version suffix):

TEMP_DIR=$(mktemp -d) && \
mkdir -p "$TEMP_DIR/introvox" && \
cp -r appinfo lib l10n templates css img js "$TEMP_DIR/introvox/" && \
cp CHANGELOG.md LICENSE README.md "$TEMP_DIR/introvox/" && \
cd "$TEMP_DIR" && \
tar -czf introvox-X.Y.Z.tar.gz introvox && \
mv introvox-X.Y.Z.tar.gz /path/to/IntroVox/ && \
rm -rf "$TEMP_DIR"

Exclude: src/, node_modules/, .git/, *.key, deploy.sh, any sample files.

6. Sign the Tarball

openssl dgst -sha512 -sign /path/to/introvox.key introvox-X.Y.Z.tar.gz \
  | openssl base64 -A > introvox-X.Y.Z.sig

7. Create the GitHub Release

gh release create vX.Y.Z introvox-X.Y.Z.tar.gz \
  --repo nextcloud/IntroVox \
  --title "vX.Y.Z - [Description]" \
  --notes "$(sed -n '/^## \[X.Y.Z\]/,/^## \[/p' CHANGELOG.md | head -n -1)"

The resulting download URL:

https://github.com/nextcloud/IntroVox/releases/download/vX.Y.Z/introvox-X.Y.Z.tar.gz

8. Submit to the App Store

See App Store Submission for the full flow. TL;DR — try the API first, fall back to the web UI if the token returns HTTP 403.

TOKEN=$(tr -d '[:space:]' < /path/to/appstore-api-token.txt)
SIG=$(cat introvox-X.Y.Z.sig)

curl -s -w "\nHTTP %{http_code}\n" -X POST \
  -H "Authorization: Token $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"download\":\"https://github.com/nextcloud/IntroVox/releases/download/vX.Y.Z/introvox-X.Y.Z.tar.gz\",\"signature\":\"$SIG\",\"nightly\":false}" \
  https://apps.nextcloud.com/api/v1/apps/releases

9. Post-Release Verification

  • Install the app from the App Store on a test server (wait for it to appear after approval)
  • Verify the version is displayed correctly in Settings → Apps
  • Test the upgrade path from the previous version (no broken configurations)
  • Sync all git remotes
  • Make a release announcement if it's a major version

Lessons Learned

These are real incidents from past releases — keep them in mind:

API Token Expires Silently (v1.4.3, May 2026)

The IntroVox App Store API token has expired without notification at least once. The release returned HTTP 403 from Route A, and the account/api-token URL was 404 at the time, requiring a hunt through the user menu to find the token page. Workaround: always have Route B (web UI) ready.

Defensive is_array() Guard (v1.4.3)

A corrupt or legacy wizard_steps_<lang> config blob caused array_filter() to crash with HTTP 500 on every GET /api/steps call, breaking onboarding for all users. The fix was a one-line is_array($steps) guard. Mirror this defensive pattern when reading any app config blob you don't fully control.

apps.nextcloud.com/api/v1/apps.json 302 Redirect (v1.5.0, May 2026)

The cert-verification endpoint now redirects to garm2.nextcloud.com. Use curl -sL (follow redirects) — without -L, the MD5 comparison silently compares against an empty string and gives a false positive of d41d8cd98f00b204e9800998ecf8427e.

False-Positive Tarball Content Scans (v1.5.0)

The "sensitive content" grep in §8.1 of the checklist matched webpack-minified bundle bytes by coincidence — Math.pow(2,...) contains the literal characters that trip an api_key= regex. Extract the tarball first, then grep -r per text-file extension. Don't pipe tar -xzf -O into one big binary blob.

Mixed sync/async chunk-race (general lesson)

Mixed sync/async imports of .vue components have caused webpack chunk-race runtime TypeErrors in other Vox apps. If you see "Cannot read property of undefined" after deploy, check for inconsistent import styles. (Not specific to IntroVox yet, but worth watching.)

Quick Commands Reference

# Regenerate translations
python3 regenerate_js_translations.py

# Production build
npm run build

# Security audit
npm audit

# Deploy to test/dev (not production)
./deploy.sh

TODO for Future Versions

  • Re-enable telemetry error logging once the license server is stable
  • Add retry logic with exponential backoff for telemetry
  • Consider a health-check endpoint for telemetry server status

See Also