diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/README.md | 1 | ||||
| -rw-r--r-- | docs/libraries.md | 4 | ||||
| -rw-r--r-- | docs/tomo.1.md | 2 | ||||
| -rw-r--r-- | docs/versions.md | 71 |
4 files changed, 75 insertions, 3 deletions
diff --git a/docs/README.md b/docs/README.md index 017e344b..60aaf08f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,6 +14,7 @@ A few topics that are documented: - [Operator Overloading](operators.md) - [Special Methods](metamethods.md) - [C Interoperability](c-interoperability.md) +- [Versioning](versions.md) ## Types diff --git a/docs/libraries.md b/docs/libraries.md index 7febb2e1..8043bfaa 100644 --- a/docs/libraries.md +++ b/docs/libraries.md @@ -151,8 +151,8 @@ that can be used by other Tomo projects. You can build a library by running If you additionally add the `-I` flag, Tomo will copy the entire directory (excluding files and directories that begin with `.` such as `.git`) into -`~/.local/share/tomo/installed/` and create a symbolic link for the library's -`.so` file (or `.dylib` file on Mac) in `~/.local/share/tomo/lib/`. +`~/.local/share/tomo_vX.Y/installed/` (where `X` and `Y` are the major/minor +version of the compiler). ### Using Shared Libraries diff --git a/docs/tomo.1.md b/docs/tomo.1.md index c77e91cf..7ccf0397 100644 --- a/docs/tomo.1.md +++ b/docs/tomo.1.md @@ -63,4 +63,4 @@ C code, which is then compiled using a C compiler of your choice. : Print the compiler version and exit. `-r`, `--run` -: Run an installed tomo program from `~/.local/share/tomo/installed`. +: Run an installed tomo program from `~/.local/share/tomo_vX.Y/installed`. diff --git a/docs/versions.md b/docs/versions.md new file mode 100644 index 00000000..b44902b2 --- /dev/null +++ b/docs/versions.md @@ -0,0 +1,71 @@ +# Versioning + +The Tomo language and Tomo libraries both use a versioning system based on a a +changelog called `CHANGES.md` that includes a human-and-machine-readable +markdown list of versions. + +The version number is parsed from the first level 2 header (i.e. line beginning +with `## `). An example CHANGES.md file might look like this: + +``` +# Version History + +## v1.2 + +Version 1.2 adds some new features: + +- Autofrobnication +- Reverse froodling + +## v1.1 + +- Added a `--moop` compiler flag + +## v1.0 + +Major version change including: + +- Deprecated snobwozzling +- Added new syntax for sleazles + +## v0.3 + +Bugfixes and new features... +``` + +When you build the compiler or a library, if this file exists, it will be used +to determine the current version (the top-most level 2 header). + +## Tomo Language Versions + +The version for the Tomo language itself will come into play in a few ways: + +1. The compiler will be installed to `tomo_vX.Y` (where `X` is the major + version number and `Y` is the minor version number). +2. A symbolic link will be installed from `tomo` to the largest version of Tomo + that is installed on your machine (e.g. `~/.local/bin/tomo -> + ~/.local/bin/tomo_v2.12`). +3. Each version of Tomo will build and install its own shared library file + (e.g. `~/.local/lib/libtomo_v1.2.so`) and headers (e.g. + `~/.local/include/tomo_v1.2/tomo.h`). +4. Tomo libraries will be installed to a separate subdirectory for each version + of the compiler (e.g. `~/.local/share/tomo_v1.2/installed`). + + +# Rationale + +I have opted to use a CHANGES.md file instead of git tags or a project +configuration file for a few reasons. The first is that I think there is real +value provided by maintaining a human-readable changelog. This approach +encourages developers to maintain one. The second is to facilitate a development +cycle where developers iterate on new features under the umbrella of a new +version number, rather than the git tag-based approach where new features are +developed in the no man's land between version tags. I also opted to use a +human-readable markdown changelog rather than a build configuration file in +order to ensure that there is no mismatch between the documentation and the +configuration. My recommendation would be to develop code on a `main` or `dev` +branch, bumping the version number pre-emptively (with an empty changelist). As +new changes come in, add them to the changelog. Then, when it's appropriate, +create a git tag to mark the current commit as the canonical one for that +semantic version. Then, make a new commit after the tagged one bumping the +version number and signaling the beginning of a new cycle of development. |