Publish and update
A published application becomes available in your organization as an organizational application. Each release is a new version, and people who installed an earlier version choose when to update.
Publish
Section titled “Publish”-
Get the application ready:
- In
manifest.json, setorganizationto your organization’s ID, and replace the placeholder texts and links. - Replace other placeholders, such as OAuth2 client IDs.
- Write the README. See below.
- In
-
Raise the version, then build and publish:
Terminal window adaptkit version minor # or patch, or majornpm run publishAdaptkit opens your browser to sign in, then uploads the application.
-
After the first upload, configure your system services in Adapt, such as your OAuth2 client secret. Register the callback URLs that Adapt shows there with each provider.
Write the README
Section titled “Write the README”Adapt shows README.md to people who are deciding whether to install your application. Write it for them, in plain language:
- what the application does, and for whom,
- how to set it up, and which accounts or services they need,
- what each vertex does, and its settings, inputs, and outputs,
- which data it uses, where that data goes, and why it needs each service,
- its limits, and where to get help.
Leave out build commands and code details. Put them in developer notes, such as DEVELOPMENT.md. The emulator’s Overview page shows your README as users will see it.
Update a published application
Section titled “Update a published application”Each version runs on its own domain, so a version’s pages always talk to its own backend. You can change your API freely. Updating an application does not change published projects: their owners release them again to use the new version.
Two things carry over from the previous version, and need care.
Settings and stored data carry over when their generation stays the same. If the new version cannot read the old data, choose a new generation, and Adapt removes the old data when a project updates:
{ "vertexConfig": { "generation": "settings_v2", "wipe": { "reason": "The settings format changed. Configure the booking page again." } }}| Contract | File | Controls |
|---|---|---|
vertexConfig |
vertex.json |
The vertex’s settings and metadata. A wipe also removes users’ signal bindings. |
configStoreVertex |
vertex.json |
The store of each vertex instance. |
configStorePlugin |
manifest.json |
Your application’s store in each project. |
Tell your users what an update removes.
Service changes
Section titled “Service changes”When a project updates, each user’s service settings carry over if the new definition is compatible. Otherwise, Adapt resets that service, and users must select their credentials again. They do not have to sign in again if their stored credentials still fit.
| Change | Settings |
|---|---|
| Required becomes optional | Kept |
| Optional becomes required | Reset |
| A variable’s schema accepts more values | Kept |
| OAuth2 scopes are removed | Kept |
| OAuth2 scopes are added | Reset |
A new oneof option, or a new optional group member |
Kept |
| A removed option or member, or a new required member | Reset |
| A renamed service | Reset |
The adapt-app skill’s state-and-compatibility.md reference has the complete rules, for example for HTTP proxies and TLS.
System services start empty in each new version. Adaptkit copies them from the previous version when it can. Check them after each upload.
Before you release an update
Section titled “Before you release an update”Ask your agent, or check yourself:
Compare booking_page/ 1.2.0 with 1.1.0. Which settings, stored data, and servicesettings change for users who update, and what must they do?The emulator cannot answer this, because each upload starts from default settings. Test with old settings and data in unit tests.