De AppExchange-release: van packageversie naar upgrade bij de subscriber

Kort antwoord: een AppExchange-release verloopt in vijf fasen: maak een beta-packageversie, valideer die, promoveer hem naar released, koppel hem aan je listing en breng daarna je subscribers over. Elke second-generation managed packageversie wordt als beta geboren, promoveren is eenrichtingsverkeer, en alleen packages die de security review hebben doorstaan kunnen naar subscriber-orgs worden gepusht.

Hoe ziet de AppExchange-release van begin tot eind eruit?

1. Maak de versie. Elke 2GP-versie wordt als beta aangemaakt. Een beta kun je installeren om te testen, maar nooit publiceren op een listing.
2. Valideer. Installeer in een schone scratch org en in een sandbox die op een echte subscriber lijkt, en draai daarna de volledige testsuite.
3. Promoveer. sf package version promote maakt van de beta een released versie.
4. Werk de listing bij. Gebruik in de Partner Console, onder Publishing en Listings, de optie Link Your Solution om de released versie te koppelen en publiceer.
5. Breng subscribers over. Zelf installeren, een recommended version of een push upgrade.

De meeste ISV-teams doen alle vijf de stappen ergens wel. Wat meestal ontbreekt is de volgorde, de poort tussen elke fase en een betrouwbaar overzicht van welke subscriber-org op welke versie draait.

Hoe maak je een packageversie upgradebaar?

Upgradebaarheid wordt bepaald door ancestry, niet door het versienummer dat je hebt ingetypt. Elke nieuwe 2GP-versie declareert een ancestor in sfdx-project.json, en Salesforce raadt ancestorVersion: HIGHEST aan zodat de ancestor je hoogst gepromoveerde versie automatisch volgt. Bestaande klanten kunnen niet upgraden naar een versie die zonder opgegeven ancestor is gemaakt, dus een enkele build zonder ancestor levert een versie op die niemand kan bereiken.

• Houd ancestry lineair, tenzij je een bewuste reden hebt om af te takken.
• Behandel de skip-ancestor-check-vlag als een incident, niet als werkwijze.
• Gebruik versienummers zoals subscribers ze lezen: major voor ingrijpende wijzigingen, minor voor nieuwe functionaliteit, patch voor kleine correcties.

Wat moet kloppen voordat je promoveert?

Promoveren is de belangrijkste poort, omdat het onomkeerbaar is.

• Een beta-versie moet voldoen aan de eis van 75% code coverage voordat hij gepromoveerd kan worden.
• Je kunt een bepaald versienummer maar een keer promoveren en releasen, en je kunt het niet terugzetten naar beta.
• De ancestor moet kloppen, want de released versie is de stap waarlangs je subscribers upgraden.

Laat promoveren draaien vanuit je pipeline, achter een expliciete menselijke goedkeuring, en nooit vanaf de laptop die toevallig bij de Dev Hub is ingelogd. De rechten om te promoveren zijn zelf een control: geef ze via een permission set in plaats van aan iedereen met CLI-toegang.

Wanneer vindt de security review echt plaats?

Bij een eerste listing zit de security review tussen validatie en publicatie, en dat is het langste onderdeel van de planning. Bij updates ligt het anders. Je hebt niet voor elke patch of upgrade een volledige security review nodig, en wat publicatie bepaalt is de status van je listing. Staat er Ready to List, dan kun je de bijgewerkte listing publiceren zonder de nieuwe versie ter review in te dienen. Staat er Security Review Required, dan kun je pas publiceren als die versie is goedgekeurd.

Salesforce voert daarnaast periodieke herbeoordelingen uit, en een versie met ingrijpende wijzigingen lokt die eerder uit. Reserveer reviewtijd dus voor releases die architectuur, authenticatie of uitgaande calls raken, en niet meer voor gewone bugfixes. Lees de actuele regels in de ISVforce-handleiding over het bijwerken van een listing voordat je er een kwartaal omheen plant.

Hoe upgrade je subscribers zonder iemand vast te zetten?

Drie knoppen, van minst naar meest ingrijpend:

1. Zelf installeren. Subscribers installeren vanaf de listing of een install-URL wanneer het hen uitkomt. De traagste convergentie, het laagste risico.
2. Recommended version. Met 2GP kun je een versie als aanbevolen markeren, waarna subscribers op hun pagina Installed Packages de optie Upgrade to Recommended Version zien. Een duwtje, geen besluit dat je voor ze neemt.
3. Push upgrade. Je upgradet de subscriber-orgs zelf en kiest welke orgs, welke versie en wanneer. Alleen packages die de AppExchange security review hebben doorstaan komen in aanmerking, de functie wordt aangezet door Salesforce Partner Support, en bij 2GP loopt een push upgrade via de CLI of de SOAP API in plaats van via de interface.

Een gefaseerde uitrol die standhoudt: eerst je eigen orgs, dan partner- en sandbox-orgs, dan een kleine groep klanten die ermee instemt, en daarna de rest in geplande batches buiten piekuren. Laat tussen de groepen genoeg tijd voor een echt supportticket, en dat is meestal een volle werkdag en geen uur.

Wat er in de praktijk misgaat

• Er is geen downgrade. Een subscriber die upgradet kan niet terug. Je rollback is een nieuwe patchversie vooruit, dus houd de release-branch in een staat waarin je die dezelfde dag kunt uitbrengen.
• De listing loopt uit de pas met het package. Een gepromoveerde versie die nooit aan de listing is gekoppeld betekent dat nieuwe prospects de build van vorig kwartaal installeren terwijl je documentatie die van dit kwartaal beschrijft.
• Ancestry breekt geruisloos. Er faalt niets tijdens de build. Het faalt maanden later, in een klantorg, als een upgrade die niet wil starten.
• Sandboxes van subscribers worden overgeslagen. Zet in je release notes dat klanten eerst een Full of Partial sandbox upgraden. Het is de enige generale repetitie die beide partijen krijgen.

Wat automatiseer je als eerste?

1. Versies aanmaken met code coverage berekend bij elke merge naar de release-branch.
2. Die beta automatisch installeren en smoke-testen in een schone scratch org.
3. Promoveren achter precies een menselijke goedkeuring, met de ancestor als eerste controle.
4. Een versieregister: welke subscriber-org draait welke versie, bijgewerkt na elke push.

Dat vierde punt stellen teams uit en daar krijgen ze spijt van, want de kwaliteit van je support hangt er meer van af dan van al het andere. Serpent ondersteunt 1GP-, 2GP- en managed-packageworkflows, cross-package dependency resolution en versiebeheer over subscriber-orgs op elk plan, inclusief het gratis plan. Meer packaging-playbooks vind je in onze SF Guides-bibliotheek.

FAQ

Kan ik een packageversie terugzetten van released naar beta?

Nee. Je kunt een versienummer maar een keer promoveren en releasen, en dat is onomkeerbaar. Behandel promoveren dus als een releasebesluit en niet als een buildstap.

Heb ik voor elke release een nieuwe security review nodig?

Nee. Een volledige review is niet nodig voor elke patch of upgrade. Publicatie hangt af van de status van je listing, en Salesforce kan nog steeds om een periodieke herbeoordeling vragen als een versie ingrijpend verandert.

Waarom kan mijn klant niet upgraden naar mijn nieuwste versie?

Meestal door ancestry. Bestaande klanten kunnen niet upgraden naar een versie die zonder opgegeven ancestor is gemaakt, dus controleer de ancestor voordat je iets anders nakijkt.

Wat is het verschil tussen een recommended version en een push upgrade?

Bij een recommended version zien subscribers de optie Upgrade to Recommended Version en bepalen ze zelf het moment. Bij een push upgrade verplaats jij hun org, op jouw schema.

Tellen beta-versies als release?

Nee. Elke 2GP-versie begint als beta en is alleen te installeren om te testen. Het wordt pas een release op het moment dat je hem promoveert.