In order to make the most of Packages, there are some best practices that Package developers and users should follow.
Intentional Package and Module versioning is very important in HyperX. This allows Package developers to inform users when meaningful changes have been made to their Packages and provides transparency about what changes have been made over time. Package developers should adhere to the Semantic Versioning scheme.
Tip
For more information about Semantic Versioning, see the Semantic Versioning site.
In previous versions of HyperX, the Plugin and Scripting API versions were tied to the HyperX version. With the introduction of Packages, the relevant API versions have now been separated from the HyperX version. This means that, for example, if a new version of HyperX is released but no breaking changes have been made to the targeted Solver Criterion API, existing Criterion Modules will continue to function.
As of HyperX version 2026.1.13, you can see the Solver and Scripting API versions for your install on the Package Manager Settings.
When a user writes a Script or Criterion Module, they must specify two levels of API compatibility:
-
The minimum or “min” version of the API that the Package is compatible with.
-
The "target" version of the API that the Package is developed and tested against.
Together, these define a range of HyperX versions that the Package is compatible with, with a lower bound of “min” and an upper bound of “target major version number + 1”.
Important
The Package Manager will refuse to load a Package that falls outside this compatibility range.
When selecting your "min" and "target" versions, consider the following:
-
The API version you code against should be your “min” and “target” version.
-
If you know that you are only using API features from an older version of the API, you can set your “min” to that version.
-
If you update your Package to use newer API features, set your “min” to the version that introduced those features.
-
If a new major API version comes out and your Script continues to work, that is, the breaking changes didn’t apply to you, update your “target” to this version.
The Package-level version is the most important version a Package developer should be aware of. This is specified using the version key in the Configuration File.
Important
If the Package developer makes changes to a Package and does not bump the Package version accordingly, users that have already installed the Package will not be able to see these changes reflected without force reinstalling the Package.
It is also good practice to provide a Package-level changelog (specified using the changelog key in the Configuration File). This is where Package developers can let users know, at a high level, what changes were made with each released version.
Tip
A best practice is to never replace a published Package version in a shared Source. If you feel that you must, consider instead deleting the offending version and publishing an updated one (with an updated version number).
The Module-level version provides Package developers an additional level of granularity when informing users about Package changes. This version can be set in the version key within a module in the Configuration File.
The Package developer can also provide a Module-level changelog (specified using the changelog key within a Modules in the Configuration File). This is where Package developers can describe what changed between one Module version and the next.
Say a Package developer has a Package which contains two Scripts, and they have implemented a bugfix for one of the two Scripts.
To follow HyperX’s Package versioning best practices, they would bump the Package version from 1.0.0 to 1.0.1 and similarly bump the specific Script Module version from 1.0.0 to 1.0.1.
The Package file (hxpkg.yaml):
id: example.script.package
name: Example
version: 1.0.1
publisher: New Package Developer
readme: readme.md
changelog: changelog.md
modules:
- type: script
id: buckling-spans
name: Buckling Span Adjustment
version: 1.0.1
main: BucklingSpanAdjustment.py
changelog: BucklingSpanAdjustmentChangelog.md
- type: script
id: export-centroid
name: Export Zone Centroids
version: 1.0.0
main: ExportZoneCentroids.py
The Package changelog (changelog.md) may look something like this:
# Changelog ## [1.0.1] - 2025-04-01 Bugfix: Fix buckling span adjustment ## [1.0.0] - 2025-01-01 Initial Package version.
And the Module changelog (BucklingSpanAdjustmentChangelog.md) may look something like this:
# Changelog ## [1.0.1] - 2025-04-01 Bugfix: Script previously used Y span instead of X span. Now it correctly uses the X span to perform the adjustment to buckling span. ## [1.0.0] - 2025-01-01 Initial script version.
Package configurational information is stored per Database. Packages and associated settings set up in a Database Template are propagated to new Databases made from the Template. There are a few common scenarios for managing Package versions among an engineering team:
Most commonly, a team will want to use the latest set of "approved" Packages. To set this up:
-
Set up a shared folder and copy approved Packages into it.
-
Add this shared folder as a Package Source to the Template.
-
Install the approved Packages in the Database Template.
As updated Package versions become available, you can vet them and copy them into your shared folder if you like the updates. Once you do, they will install automatically for everyone on the team.