Making Releases

Determine new version number according to semantic versioning conventions

Semantic Versioning in FASTSim¶

FASTSim uses the following semantic versioning rules:

• All vehicles serialized within a major version must be loadable within the same major version

  • Example: A vehicle made in v3.0.5 must be loadable in FASTSim versions up to (not including) v4.0.0

  • Vehicle models specify a minimum FASTSim version they are compatible with (within a major version)

    • Loading a vehicle model designed for a more recent version of FASTSim will throw a warning, but still be attempted

  • New fields introduced within a major version must be optional, or set a sensible default value

• Breaking changes:

  • Major version increments (e.g. 3.x.y -> 4.0.0) may include breaking changes to the Python API

    • Removal of functions, function naming, Python-exposed object naming/structure, etc.

  • Minor version increments (e.g. 3.0.x -> 3.1.0) may include breaking changes to the Rust API

    • Alterations to Rust-only functions, function naming, structures, etc.

    • Downstream Rust projects should use tilde requirements

      • Example Cargo.toml dependency on FASTSim:

        [dependencies]
        fastsim-core = "~3.1" 
        # - allows 3.1.0, 3.1.1, etc.,
        # - disallows >= 3.2.0

        Or:

        [dependencies]
        fastsim-core = "~3.1.1"
        # - allows 3.1.1, 3.1.2, etc.,
        # - disallows < 3.1.1, >= 3.2.0

  • Patch version increments (e.g. 3.0.0 -> 3.0.1) are for bug fixes only, no intentional breaking changes

In summary:

Update FASTSim version in the following locations:

• pyproject.toml

• fastsim-core/Cargo.toml

  • package version

  • fastsim-proc-macros dependency version

• fastsim-core/fastsim-proc-macros/Cargo.toml

• fastsim-py/Cargo.toml

Commit these changes via git

Tag the latest commit with your version number and push

git tag vX.Y.Z

git push origin vX.Y.Z

Draft a new release at https://github.com/NatLabRockies/fastsim/releases/new

• Select the newly created tag

• Autogenerate release notes

• Add extra description of changes, new features, bugfixes, etc.

Publish release

• GitHub Actions will take care of testing, building wheels, and releasing to PyPI and crates.io