exchange work
This commit is contained in:
@@ -0,0 +1,130 @@
|
||||
---
|
||||
name: ignition-exchange-publish
|
||||
description: Package and upload a finished Ignition resource to the Ignition Exchange — which file format to export, what to verify inside the archive before uploading, and what to put in every field of the Exchange upload form (title, tagline, categories, version, minimum Ignition platform, required modules, package files, custom installation instructions). Use when asked how to publish, export, or upload an Ignition project to the Exchange, or what format the Exchange expects. Not for checking conformance (use ignition-exchange-conformance) or converting a project into Exchange shape (use ignition-exchange-convert).
|
||||
---
|
||||
|
||||
# Publishing to the Ignition Exchange
|
||||
|
||||
## The artifact is a project export `.zip`
|
||||
|
||||
Produced by **Designer → File → Export**, or **Gateway → Config → Projects →
|
||||
*project* → Export**. Both give the same file.
|
||||
|
||||
> **Never upload a gateway backup (`.gwbk`).** It contains the entire gateway —
|
||||
> datasource credentials, journal profiles, tags, every other project. Wrong
|
||||
> artifact, and it leaks configuration into a public resource.
|
||||
|
||||
A repo that stores projects as unpacked files (the gateway-as-files pattern) has
|
||||
no zip in it — one has to be generated.
|
||||
|
||||
## What goes in the upload
|
||||
|
||||
The Exchange accepts multiple package files, 10 MB each.
|
||||
|
||||
| File | Upload as | When |
|
||||
|---|---|---|
|
||||
| `<resource>.zip` | Package file | Always — the project export |
|
||||
| `README.md` / PDF | Package file | Always, as a **separate** file |
|
||||
| Tag export `.json` | Package file | Only if it needs tags/UDTs |
|
||||
| Database dump `.sql` | Package file | Only if it needs a schema or seed data |
|
||||
| Screenshots | Images & Screenshots | Optional, strongly encouraged |
|
||||
|
||||
**The README is probably not inside the zip.** Ignition's export serialises
|
||||
recognised project resources — each is a directory with a `resource.json`. A
|
||||
loose `README.md` at the project root is not one, so the export is expected to
|
||||
drop it. Unzip and check rather than assuming. The guide asks for docs as a
|
||||
separate package file regardless:
|
||||
|
||||
> **Note:** If you already have detailed documentation for your resource please
|
||||
> note it here and include the documentation file in the Package File upload.
|
||||
|
||||
Note that a conformance checker's documentation rule inspects the working
|
||||
directory, not the archive — a passing lint does not prove the zip carries docs.
|
||||
|
||||
## Before packaging
|
||||
|
||||
The guide names four pre-upload checks. Three are often N/A; the first never is.
|
||||
|
||||
1. **Check the project export** — import the zip into a brand-new project, *and*
|
||||
into a project that already has content. The second is the case the whole
|
||||
namespacing convention exists for and the only way to prove nothing collides.
|
||||
2. **Include the tags** — if it binds to tags or UDTs, export them and verify
|
||||
coverage.
|
||||
3. **Database backups** — if it expects tables or seed data, include the dump and
|
||||
name the vendor (MySQL / MSSQL / PostgreSQL) in both the description and the
|
||||
install instructions.
|
||||
4. **Take notes while testing** — they become the Custom Installation
|
||||
Instructions. Readers range from beginner to intermediate.
|
||||
|
||||
## Verify the archive
|
||||
|
||||
```bash
|
||||
unzip -l <resource>.zip
|
||||
unzip -o <resource>.zip -d /tmp/verify-export
|
||||
```
|
||||
|
||||
- File count matches the project on disk, minus anything the export legitimately drops
|
||||
- Every view, style class and script module present
|
||||
- `README.md` presence — confirm, do not assume
|
||||
- No `.resources/` (gateway-owned cache), `__pycache__`, editor backups
|
||||
- No credentials anywhere
|
||||
|
||||
## The upload form
|
||||
|
||||
### Overview
|
||||
|
||||
| Field | Guidance |
|
||||
|---|---|
|
||||
| Visibility | `Public` unless genuinely private |
|
||||
| Title | Short, Title Case, says what it does; usually matches project title |
|
||||
| Tagline | One sentence, must **not** repeat the title |
|
||||
| Description | What it does, how it's used, who benefits, relevant industries |
|
||||
| Resource Type | Closest dropdown match + skill level for install/use complexity |
|
||||
| Background Image | Optional card styling |
|
||||
| Category | **Up to 3**: Alarming, Analytics, Connectivity, Dashboard, Diagnostics, Edge Computing, Enterprise, HMI, IIOT/MQTT, MES, Maintenance, Mapping/GIS, Mobile, Monitoring, Reporting, SCADA, Scripting, Security, Simulation, Trending/Charting, Utility |
|
||||
| Contact the Developer | Optional; your address is never shown |
|
||||
| Tags | **Up to 10** search keywords |
|
||||
| Images & Screenshots | Optional, highly encouraged |
|
||||
|
||||
### Package
|
||||
|
||||
| Field | Guidance |
|
||||
|---|---|
|
||||
| Version | `1.0.0` first release; later auto-increment. **Never** put the version in the project name |
|
||||
| Ignition Platform | The **minimum** required. Guide: *"If unsure, select the Ignition platform version in which the package was developed with."* Do not claim an untested floor |
|
||||
| Release Tagline | Short summary of this version's changes; required even for the first |
|
||||
| Release Notes | Fuller explanation of what changed and its impact |
|
||||
| Required Modules | IA / Cirrus Link / Sepasoft modules needed |
|
||||
| Maker Edition | Tick if it runs on Maker; unavailable if you require unsupported modules |
|
||||
| Other Requirements | External prerequisites, one per line; blank if none |
|
||||
| Package Files | The zip plus docs / tags / SQL |
|
||||
| Custom Installation Instructions | Step-by-step; assume a beginner. If you shipped separate docs, say so here |
|
||||
|
||||
The Exchange **auto-generates a readme** from the Description and Custom
|
||||
Installation Instructions — write both properly.
|
||||
|
||||
## Verifying a minimum-version claim
|
||||
|
||||
Load the project on a throwaway gateway at the version you intend to declare,
|
||||
using a **copy** of the files — an older gateway rewrites `resource.json`
|
||||
metadata and leaves root-owned `.resources/` behind.
|
||||
|
||||
A clean load proves resources parse. It does **not** prove screens render: a
|
||||
component property added in a later version fails at render time. Open the
|
||||
client and look. If you cannot test the lower version, declare the version you
|
||||
developed on.
|
||||
|
||||
## After publishing
|
||||
|
||||
- Updates are **new package versions on the same resource**, not new resources.
|
||||
- **Never rename the namespace folders between versions** — that turns an upgrade
|
||||
into a duplicate set of resources in every user's project.
|
||||
- Re-run conformance before every release.
|
||||
- Non-English resources: the guide encourages shipping a language dropdown with
|
||||
English alongside.
|
||||
|
||||
## Provenance
|
||||
|
||||
Field list and quoted text from Exchange Resources Style Guide v1.1.0, §Before
|
||||
You Upload and §Uploading to the Exchange. Export-drops-README is reasoning from
|
||||
how Ignition serialises resources, not an observed export — verify it.
|
||||
Reference in New Issue
Block a user