Document best practices for developing "bbin-ready" bb scripts

[bzg]

I developed a few bb scripts for which I recommend direct raw file bbin installation (e.g. here).

But now I hit a limit: what if I want to version these scripts?

I see antq.clj use ad hoc versioning. Is this the recommended way?

Do I need to dedicate a repo to a script to set its version in a bb.edn file? in a version.edn file?

How does neil interplay (because I see this deps adds a version related to neil)?

Not sure where to start but my main question is: what are the best practices for developing "bbin-ready" bb scripts?

[rads]

I developed a few bb scripts for which I recommend direct raw file bbin installation (e.g. here).

But now I hit a limit: what if I want to version these scripts?

I see antq.clj use ad hoc versioning. Is this the recommended way?

This specific script is a wrapper around the antq library which already has its own version. The (def version ...) in the code is not the version of the antq.clj file itself.

In this case, the antq.clj file is installed using the following command:

# Install `.clj` file with latest version
bbin install https://raw.githubusercontent.com/borkdude/tools/main/antq.clj

Since it's coming directly from the main branch of the Git repo, the version of ant.clj is the SHA that main points to (currently d4ad9f).

Do I need to dedicate a repo to a script to set its version in a bb.edn file? in a version.edn file?

If you're installing scripts directly as .clj files and you want to install a specific version, you can change the URL to use the version you want:

# Install `.clj` file with Git tag as version
bbin install https://raw.githubusercontent.com/borkdude/tools/refs/tags/v0.0.1/antq.clj

# Install `.clj` file with Git SHA as version
bbin install https://raw.githubusercontent.com/borkdude/tools/ce1377a91dcdc1d553d7f65a7278b3a359396cd9/antq.clj

(The first example doesn't actually work because there is no v0.0.1 tag in that repo, but publishing a Git tag is all that's required to fix it.)

How does neil interplay (because I see this deps adds a version related to neil)?

If you use semantic versions (e.g. 0.1.0), neil version is just a tool to save you from manually doing all the little commands required to bump the version and create the Git commit/tag. It's very similar to npm version except the version is stored in deps.edn instead of package.json. When installing scripts, bbin doesn't use the :neil :project :version at all (though I do use neil version for publishing bbin releases).

Not sure where to start but my main question is: what are the best practices for developing "bbin-ready" bb scripts?

All Babashka scripts and projects are already "bbin-ready". To install a single .clj file with a version, you can use the URL (as described above) to version the script. To install a deps.edn project, you use the same keys you'd use as if you were including it as a dependency in a Clojure or Babashka project using deps.edn:

• Maven: --mvn/version
• Git: --git/url, --git/tag, --git/sha
• Filesystem: --local/root

[bzg]

Thank you very much for your reply! I will rethink what my problem is and try to either restate it and/or suggest a solution.

[bzg]

I restate this as a proposal to remove deps.edn as a requirement for install methods other than the raw HTTP url install. Thanks!