Developing and publishing a package

A package lives in its own repository. To start one, run jadpo package new <Name> --library or --provider. It writes the package format, plus recipes/, a sample/ app that the recipes and tests run against, and GUIDE.md, with a small example of each to replace (jadpo package new). It passes jadpo package check as written. Its licence is Licence.proprietary until you choose another, and its publisher is whoever you name with --publisher.

Developing it

• jadpo test runs the package's tests, the examples in its descriptions, its decoders against its recordings, and its recipes compiled into sample/.
• jadpo package record and conform work against the provider's sandbox.
• jadpo package check runs the whole publishing bar locally, writes surface.jadpo_record, and compares it with the surface at the previous tag.

Trying it in an app before publishing

jadpo package link ../acme-pricing compiles the app against the live checkout and records the link in the lock. jadpo build for production, and CI, refuse a link, so it can never ship. jadpo package unlink restores the installed version.

Private packages come from git

jadpo package add github.com/acme/acme-pricing@v2.1.0 installs a private package. A version is a git tag, which the package's CI adds only after jadpo package check passes. Access is the developer's or CI's own git access. There is no jadpo login and no private registry: packages are committed into apps, so a registry's caching would add nothing.

Public packages

Public packages go to the registry with jadpo package publish, from a tag (Releasing). The registry isn't live yet, so to share a package today, give people its repository and a tag.

jadpo package link <folder> writes package Postcodes.v2 link ../postcodes in the lock and keeps the line it replaced in .jadpo/links; from then on every jadpo check, test and dev reads the checkout's files in place of packages/postcodes/v2/, which stays as installed, and shows its problems at the checkout's paths. With CI set, jadpo check and jadpo test refuse the link (install.link_refused), and jadpo build will always. jadpo package unlink postcodes puts the installed line back:

text

$ jadpo package link ../postcodes✓ Linked Postcodes.v2 to ../postcodes    checkout   ../postcodes    installed  2.1.0, restored by jadpo package unlink postcodes✓ package linked  Postcodes.v2 · the app checks against it→ jadpo package unlink postcodes  goes back to the installed version before you push

What publishing requires

jadpo package publish, and jadpo package check before a tag, refuse a package unless:

1. it compiles with no errors and no warnings;
2. every public type, failure, library and library function has a /// description;
3. every function of a public library has at least one example in its description, compiled and run at publish, and every failure it can raise is shown by an example or a test;
4. its tests pass, every decoder decodes every recorded response, a field's decode and encode pair round-trips, and every recipe compiles and passes its tests in sample/;
5. its version agrees with the surface diff;
6. its changelog's list of changes is generated from the surface diff, and the author writes only why;
7. it declares a licence from the fixed list (not .proprietary, for the public registry) and the lowest Jadpo version it needs;
8. it names its publisher.

The bar applies only to what is published: the app's own integrations and libraries skip it. Examples are part of the bar because they must run, which the compiler can check.

A library package also ships complete wording in its own default locale, with a /// description on every public message (Packages' text in an app). The bar's wording row, shown when the package carries translations, holds every language the package ships to completeness, and item 2 asks for the description of every public message.

jadpo package check, run in a package's own repository, checks the package placed as the app's own integration in a scratch app (the golden rule) and shows each problem at its place in the package's folder. Item 1 is the check itself, type.standard_exists on the package's public types among it (Standard library); item 2 is publish.description_missing; item 4's tests are the package's own .test.jadpo files; item 5 works out the version from the surface at the last tag and refuses a breaking change (publish.breaking_change); item 7 is the index's own check and the licence row: check passes Licence.proprietary, because a private package's CI runs it before a tag, and verify and publish refuse it (publish.licence_proprietary). Item 8 is the publisher row: check says left out and passes, because a private package's CI runs it before a tag, and verify and publish refuse the package (publish.publisher_missing). Item 4's decoders are the decoders row, every decoder over every recording with each field's decode: and encode: round-tripping ("Recording errors"), and its recipes the recipes row (under "Recipes"). The surface is written whenever the package compiles and its version is allowed.

Item 3: each ```jadpo block in a public declaration's /// description runs as a test of the package, a function of a public library without one is publish.example_missing, as is a failure it can raise that no example or test asserts with fails, and an example that doesn't compile or hold is publish.example_failed at its line in the description. Item 6: the new version's section of CHANGELOG.md is written from the surface's changes, and a release whose section says nothing beneath the list is publish.changelog_missing:

text

$ jadpo package checkFacts  kind       library, pure  publisher  @acme  storable   OutwardCode, UkPostcode, WrittenPostcode  failures   uk.tidy: InvalidPostcodeChanges since 2.0.0  + added  type OutwardCodePublishing bar✓ compiles      passed                        no errors✓ described     passed                        every public declaration✓ examples      passed                        2 examples, every failure shown✓ tests         passed                        3 tests✓ behaviour     passed                        all 5 from 2.0.0 hold✓ version       passed                        2.1.0, 1 added since 2.0.0✓ changelog     passed                        2.1.0 says why✓ publisher     passed                        @acme✓ licence       passed                        mit, from Jadpo 1.0✓ Wrote surface.jadpo_record and CHANGELOG.md✓ package check passed  Postcodes.v2 2.1.0 · 9 passed→ git tag v2.1.0  tags the release once surface.jadpo_record is committed

An example is a test's body in the description; the changelog's list is the first list under its version, and the author writes why beneath it:

text

/// Reads a postcode in upper case.////// ```jadpo/// var postcode: UkPostcode = attempt uk.tidy("sw1a 1aa")/// assert postcode == "SW1A 1AA"/// assert uk.tidy("x") fails InvalidPostcode/// ```function tidy(entered: EnteredPostcode) fails InvalidPostcode -> UkPostcode {

text

# Changelog## 2.1.0- added type `OutwardCode`Reads the outward code, for delivery zones.## 2.0.0- first releaseUK postcodes, read as people type them.