1 # Versioning
   2 
   3 The Tomo language and Tomo libraries both use a versioning system based on a
   4 changelog called `CHANGES.md` that includes a human-and-machine-readable
   5 markdown list of versions.
   6 
   7 The version number is parsed from the first level 2 header (i.e. line beginning
   8 with `## `). An example CHANGES.md file might look like this:
   9 
  10 ```
  11 # Version History
  12 
  13 ## v1.2
  14 
  15 Version 1.2 adds some new features:
  16 
  17 - Autofrobnication
  18 - Reverse froodling
  19 
  20 ## v1.1
  21 
  22 - Added a `--moop` compiler flag
  23 
  24 ## v1.0
  25 
  26 Major version change including:
  27 
  28 - Deprecated snobwozzling
  29 - Added new syntax for sleazles
  30 
  31 ## v0.3
  32 
  33 Bugfixes and new features...
  34 ```
  35 
  36 The versions here use a `vMAJOR.MINOR` semantic versioning style, but this is
  37 not required. Versions can be any string literal, for example:
  38 `edition-2025-11-29` or `1.2.3` or `6.1-EliteOcelot`.
  39 
  40 When you build the compiler or a library, if this file exists, it will be used
  41 to determine the current version (the top-most level 2 header).
  42 
  43 ## Tomo Language Versions
  44 
  45 The version for the Tomo language itself will come into play in a few ways:
  46 
  47 1. The compiler will be installed to `tomo@TOMO_VERSION` (where `TOMO_VERSION`
  48    is the verion of the Tomo compiler).
  49 2. A symbolic link will be installed from `tomo` to the largest version of Tomo
  50    that is installed on your machine (e.g. `~/.local/bin/tomo ->
  51    ~/.local/bin/tomo@v2025-11-29.1`).
  52 3. Each version of Tomo will build and install its own shared library file
  53    (e.g. `~/.local/lib/libtomo@v2025-11-29.1.so`) and headers (e.g.
  54    `~/.local/include/tomo@v2025-11-29.1/tomo.h`).
  55 4. Tomo libraries will be installed to a separate subdirectory for each version
  56    of the compiler (e.g. `~/.local/lib/tomo@v2025-11-29.1/`).
  57 
  58 ## Tomo Program Versions
  59 
  60 When you write a Tomo program (say, `foo.tm`) and run it, Tomo will
  61 automatically add support for parsing a version number out of an accompanying
  62 `CHANGES.md` file in the same directory. You can use the `--version` flag to
  63 print the version number and exit. For example, if I run `tomo foo.tm --
  64 --version`, it will print `v0` if no `CHANGES.md` file exists, otherwise it
  65 will compile the program with the most recent version number from that file and
  66 print it instead. Similarly, if you run `tomo -e foo.tm` to build `foo` as a
  67 standalone executable and then run `./foo --version`, it will print the version
  68 number and exit without running the program.
  69 
  70 ## Tomo Library Versions
  71 
  72 Tomo libraries also have version numbers. When you install a library, its
  73 version number will be used to determine its installation location and how it's
  74 used in code. You must either explicitly import the library with its version
  75 number (e.g. `use foo@v1.2`) or include a `modules.ini` configuration file that
  76 maps a shorthand alias to a specific version of a library. For example, if the
  77 `modules.ini` file has a `[foo]` section with `version=v1.2`, you can put `use
  78 foo` to use v1.2 of the `foo` library (assuming you have it installed).
  79 
  80 # Rationale
  81 
  82 I have opted to use a CHANGES.md file instead of git tags or a project
  83 configuration file for a few reasons. The first is that I think there is real
  84 value provided by maintaining a human-readable changelog. This approach
  85 encourages developers to maintain one. The second is to facilitate a development
  86 cycle where developers iterate on new features under the umbrella of a new
  87 version number, rather than the git tag-based approach where new features are
  88 developed in the no man's land between version tags. I also opted to use a
  89 human-readable markdown changelog rather than a build configuration file in
  90 order to ensure that there is no mismatch between the documentation and the
  91 configuration. My recommendation would be to develop code on a `main` or `dev`
  92 branch, bumping the version number pre-emptively (with an empty changelist). As
  93 new changes come in, add them to the changelog. Then, when it's appropriate,
  94 create a git tag to mark the current commit as the canonical one for that
  95 semantic version. Then, make a new commit after the tagged one bumping the
  96 version number and signaling the beginning of a new cycle of development.