{"id":18402380,"url":"https://github.com/luchiniatwork/orzo","last_synced_at":"2025-07-21T23:32:14.779Z","repository":{"id":62433488,"uuid":"161579746","full_name":"luchiniatwork/orzo","owner":"luchiniatwork","description":"Collection of composable functions for easily setting up any version strategy for your project.","archived":false,"fork":false,"pushed_at":"2023-02-07T23:01:46.000Z","size":72,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-15T06:05:27.790Z","etag":null,"topics":["automation","build","ci","clojure","version-control","versioning"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luchiniatwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-13T03:38:03.000Z","updated_at":"2025-06-04T20:51:38.000Z","dependencies_parsed_at":"2024-11-06T03:08:17.437Z","dependency_job_id":null,"html_url":"https://github.com/luchiniatwork/orzo","commit_stats":{"total_commits":34,"total_committers":3,"mean_commits":"11.333333333333334","dds":0.5294117647058824,"last_synced_commit":"f04d79e21c21b8fc8d27ad5007fea40bf799051d"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/luchiniatwork/orzo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luchiniatwork%2Forzo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luchiniatwork%2Forzo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luchiniatwork%2Forzo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luchiniatwork%2Forzo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luchiniatwork","download_url":"https://codeload.github.com/luchiniatwork/orzo/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luchiniatwork%2Forzo/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266403053,"owners_count":23923403,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-21T11:47:31.412Z","response_time":64,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","build","ci","clojure","version-control","versioning"],"created_at":"2024-11-06T02:42:21.419Z","updated_at":"2025-07-21T23:32:14.745Z","avatar_url":"https://github.com/luchiniatwork.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Orzo\n\n[![CI](https://github.com/luchiniatwork/orzo/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/luchiniatwork/orzo/actions/workflows/ci.yml)\n[![Clojars Project](https://img.shields.io/clojars/v/luchiniatwork/orzo.svg)](http://clojars.org/luchiniatwork/orzo)\n[![cljdoc badge](https://cljdoc.org/badge/luchiniatwork/orzo)](https://cljdoc.org/d/luchiniatwork/orzo/CURRENT)\n![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)\n![Beta Project](https://img.shields.io/badge/project%20status-beta-brightgreen.svg)\n\nOrzo lets you manage the versioning strategy of any project from one\nsingle place.\n\n## Table of Contents\n\n* [Getting Started](#getting-started)\n* [Motivation](#motivation)\n* [Usage](#usage)\n* [Bugs](#bugs)\n* [Help!](#help)\n\n## Getting Started\n\nAdd `orzo` as a dependency in your `deps.edn` file (possibly as an\nalias as shown below):\n\n``` clojure\n{:aliases\n {:orzo {:extra-deps\n         {luchiniatwork/orzo {:mvn/version \"23.2.5\"}}}}}\n```\n\n`orzo` has a series of composable functions specifically designed to\nimplement versioning strategy. You can see other example in\n[Usage](#usage) below or refer to the [API\ndocs](https://cljdoc.org/d/luchiniatwork/orzo/CURRENT) to compose your\nown strategy.\n\nFor the sake of this getting started, lets assume you want a semver\nstrategy that composes the major and minor from a text file with a\npatch that is the job number of your build server.\n\nAssumption one: you have a file `resources/base_version.txt` that\ncontains:\n\n``` text\n1.2\n```\n\nAssumption two: your build server places the build number on an\nenvironment variable called `BUILD_NUM`.\n\nAssumption three: you want to save the calculated version into a file\nat `resources/version.txt` so that your users are able to identify\nthis built.\n\nAssumption four: if everything goes fine (assuming your build server\nruns tests as well) you want to tag your repo with the version number\nprefaced with a `v` (as in `v0.4.542`).\n\nIn order to accomplish these you'll first need to create a script\ncalled `gen_version.clj` on your classpath:\n\n``` clojure\n(ns gen-version\n  (:require [orzo.core :as orzo]))\n\n(defn -main [\u0026 args]\n  (try\n    (println (-\u003e (orzo/read-file \"resources/base_version.txt\")\n                 (orzo/extract-base-semver)\n                 (orzo/set-semver {:patch (orzo/env \"BUILD_NUM\")})\n                 (orzo/save-file \"resources/version.txt\")\n                 (orzo/stage)))\n    (System/exit 0)\n    (catch Exception e\n      (println e)\n      (System/exit 1))))\n```\n\n`orzo` works with composable functions that can be easily piped with a\nthread-first macro.\n\nThe first function `orzo/read-file` reads the first line of\n`resources/base_version.txt` and returns its contents.\n\n`orzo/extract-base-semver` will take that version just read and return\na semver object that can be manipulated.\n\nFor the next line we use `orzo/set-semver` to set the `:patch` of the\nsemver with whatever is the content of the environment variable\n`BUILD_NUM` (read here with another `orzo` function `orzo/env`).\n\nWe then save the generated version with `orzo/save-file` so that it\ncan be read by users of this packaged later.\n\n`orzo` also offers a convenient function for \"staging\" the version so\nthat it can be used at a later point. The function here is\n`orzo/stage` and it's usually the last one in the script.\n\nTo run the script above:\n\n``` shell\n$ clojure -A:orzo -m gen-version\n```\n\nIf your base version file is `1.2` and your build number is `451` you\nshould see:\n\n``` text\n1.2.451\n```\n\nTip: if you are testing it locally and do not have an environment\nversion `BUILD_NUM` set, simply run:\n\n``` shell\n$ BUILD_NUM=451 clojure -A:orzo -m gen-version\n```\n\nStaging the version is important for the next script. We will call it\n`tag_and_push_version.clj`:\n\n``` clojure\n(ns tag-and-push-version\n  (:require [orzo.core :as orzo]\n            [orzo.git :as git]))\n\n(defn -main [\u0026 args]\n  (try\n    (println (-\u003e (orzo/unstage)\n                 (orzo/prepend \"v\")\n                 (git/tag)\n                 (git/push-tag)))\n    (System/exit 0)\n    (catch Exception e\n      (println e)\n      (System/exit 1))))\n```\n\nThis script is recovering the version that was staged by the previous\nscript with `orzo/unstage`. Then it prepends it with a `v`, creates a\ntag (`orzo/tag`) and pushes the tag back to your origin\n(`orzo/push-tag`).\n\nOf course you will only run this script if the build was\nsuccessful. In such case, run it with:\n\n``` shell\n$ clojure -A:orzo -m tag-and-push-version\n```\n\n## Motivation\n\nVersioning is a concern in every single project. `orzo` is a simple,\nconfigurable and extensible tool to implement any versioning strategy\nyour project requires.\n\n## Usage\n\nAll functions withing `orzo` are composable via thread-first\nmacros. Such a practice allows for very short and easy-to-read scripts.\n\nFor a detailed insight over each function, do refer to the [API\ndocs](https://cljdoc.org/d/luchiniatwork/orzo/CURRENT).\n\nThe functions are grouped by informational functions, transformation\nfunctions, validation functions and persistence functions.\n\n**Informational functions** read some information from the system into the\nstream. Examples are `orzo.core/env` or `orzo.core/read-file` that\nread an environment variable or a file, respectively. Many other\nfunctions fall into that category, for instance `orzo.git/last-tag`\nthat extracts the last tag from git.\n\n**Transformation functions** alter the version in the\npipeline. Examples are `orzo.core/append`\n`orzo.core/extract-base-semver` or `orzo.core/bump-semver`. These let\nyou append a value to the version, transform the version into semver\nor bump certain semver indicators.\n\n**Validation functions** will throw if something is wrong. For\ninstance `orzo.git/assert-clean?` will throw if the repo is not clean\nlocally.\n\n**Persistence functions** are usually at the very end of `orzo`\nscripts. They will have side effects and therefore must be used\ncarefully. `orzo.core/save-file` is a great example where a file is\nsaved with the version passed to it. Other examples are `orzo.git/tag`\nand `orzo.git/push`. Both functions have implications on your git\nrepo (locally and remotely, respectively).\n\n## Bugs\n\nIf you find a bug, submit a [GitHub\nissue](https://github.com/luchiniatwork/orzo/issues).\n\n## Help\n\nThis project is looking for team members who can help this project\nsucceed!  If you are interested in becoming a team member please open\nan issue.\n\n## License\n\nCopyright © 2023 Tiago Luchini\n\nDistributed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluchiniatwork%2Forzo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluchiniatwork%2Forzo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluchiniatwork%2Forzo/lists"}