A package is identified by its name and its version together: my-bot 1.0.0 and my-bot 1.0.1 are two packages in your library. The way you number versions matters once other people use your package.
Where a name and a version come from
Neither is written in the package's files. A package gets them from how it was installed:
| How | Name and version |
|---|---|
| New package, Import a .zip, Copy to a new version | The Name and Version typed in the dialog |
The library install command |
The --name and --version flags |
| Installing from the marketplace | Built from the file on asterobot.net. See How your package is named. |
Asterobot stores each version in its own folder of the library, named after the package and the version, which is why the two follow the rules below. You can't rename a package or change its version in place. Copy it to a new name or version, or export it and import it again.
Local names
A local name is a plain name, such as my-bot. Only local packages can be edited in Asteroboard.
- It can't contain
@or:, since both mean something in marketplace names and in imports. - It can't be empty,
.or.., and can't contain/or\. - Everything else is allowed, dots included, even at the start as in
.dotted. Lowercase words joined by hyphens, such aschat-logger, read best in lists and inimportstatements.
Marketplace names
A marketplace name looks like @publisher:name, such as @alice:chat-tools. Asterobot gives one to every package installed from the marketplace.
- The name starts with
@, then a publisher, a:and a name, and contains no other@or:. - A publisher of
asterobotmakes an Official package. Any other publisher makes a Community package. - The Import a .zip dialog and
library installalso accept a name of this shape. The package then shows Community or Official without coming from the marketplace, and it can't be edited or copied in Asteroboard.
| Name | Accepted | Why |
|---|---|---|
my-bot |
Yes | A local name |
.dotted |
Yes | A local name |
@alice:chat-tools |
Yes | A community name |
@asterobot:core |
Yes | An official name |
my@bot |
No | Reads as the package my at version bot |
local:bot |
No | A : introduces a name after a publisher, and there's no @ |
@alice, @alice:, @:chat-tools |
No | The publisher or the name is missing |
@alice:chat:tools, @alice:chat@tools |
No | A second : or @ |
The dialogs refuse a wrong name as you type:
| Message | Where |
|---|---|
A local package name can't contain ':' or '@'. |
New package, Import a .zip, Copy to a new version |
A new package is local, so its name can't start with '@' - those are assigned by the marketplace. |
New package and Copy to a new version, which only create local packages |
A marketplace name looks like @publisher:name. |
Import a .zip |
A marketplace name has exactly one ':' and one leading '@'. |
Import a .zip |
The command line gives Asterobot's own wording, such as local package name "my@bot" must not contain ":" or "@", marketplace package name "@alice" must be "@publisher:name" or marketplace package name "@alice:chat:tools" must contain exactly one ":" and one leading "@".
Version numbers
A version is required, and Asterobot accepts almost any text: it can't be . or .., and can't contain / or \. New packages start at 1.0.0. A version breaking these rules is refused with invalid version "<version>": contains a reserved character, or empty or reserved path component. Copy to a new version shows that reason, while New package and Import a .zip only show a toast.
Use semantic versions
Write versions as three numbers separated by dots, such as 1.4.2: a semantic version. Asterobot accepts other text, but several features only understand semantic versions:
| Feature | With semantic versions | With other text |
|---|---|---|
| Check for updates | Offers a version only when it's higher than the installed one | Offers any different version, even an older one |
Version ranges such as ^1.2.0 or latest, in imports and in dependencies |
Consider this version | Skip this version, as if it weren't installed |
| Declaring the package as a dependency | Works | Save manifest refuses the version |
| Copy to a new version | Suggests the next version: 1.4.2 becomes 1.4.3 |
Raises the last number in the text, or suggests the same version when there's no number |
The usual meaning of the three numbers helps the people who use your package, especially other authors who depend on it with a range such as ^1.2.0, which accepts any 1.x.y from 1.2.0 on:
- Raise the last number for a fix that changes nothing else:
1.4.2to1.4.3. - Raise the middle number when you add something without breaking what exists, and reset the last one:
1.4.3to1.5.0. - Raise the first number when something that worked before stops working: a setting renamed, an exported function removed or changed. Reset the other two:
1.5.0to2.0.0.
Some details of how Asterobot reads semantic versions:
1,1.4andv1.4.2are understood too, but they're different text from1.4.2. An exact version is always compared as text, so a dependency locked to1.4doesn't match an installed1.4.0. Write three numbers, withoutv, everywhere.- Numbers can't have leading zeros:
1.04.0isn't a semantic version. - A suffix after a hyphen, as in
2.0.0-rc.1, makes a version that comes before2.0.0. Check for updates offers2.0.0to someone on2.0.0-rc.1, never the reverse, and ranges only match such versions when the range itself has a suffix. - A suffix after
+, as in1.4.2+build.7, doesn't change the order.
Versions side by side
Each version of a package is installed on its own, and stays until someone removes it. A bot is set to one exact version, so installing a new version never changes what a bot plays. Update packages describes this from the player's side.
For you as the author:
- To start a new version, use Copy to a new version on the current one, as Share your package shows. The old version stays as it was.
- Give every change you share a new version. Two packages with the same name and version can't be told apart, and the second one installed replaces the first.
- Settings are saved under the package's name, so a bot moved to a new version keeps its values, and a package copied under a new name starts from its defaults on every bot. See Read settings.
- A script can load several versions of the same package at once, when its dependencies lock different versions. See Dependencies.
Next, Dependencies.
Aucun avis à afficher.