Version watermarking by Dune

[nekketsuuu]

What's new?

This PR implements more detailed version strings.

$ opam pin remove satysfi
$ git clone -b nekketsuuu-watermarking https://github.com/nekketsuuu/SATySFi.git
$ cd SATySFi
$ git tag -a -m "virtual release for testing" v0.0.4
$ opam pin add satysfi .
(omit.)
$ satysfi --version
  SATySFi version v0.0.4
$ touch foobar
$ git add foobar
$ git commit -m "test commit"
[nekketsuuu-watermarking b0b3c65] test commit
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 foobar
$ opam reinstall satysfi
(omit.)
$ satysfi --version
  SATySFi version v0.0.4-1-gb0b3c65
$ opam pin remove satysfi  # Confirm to remove the tag "v0.0.4" from an OPAM cache

In the version string v0.0.4-1-gb0b3c65 in the nearly last line, 1 means that it is 1 commit ahead from v0.0.4, and gb0b3c65 means its commit hash "b0b3c65..." by git. This is the same as the output of git describe --dirty --always.

By this PR, we can:

• easily show an accurate version string, and
• easily update a version string (it's unnecessary to update the OPAM file).

Miscellaneous notes

• Currently, satysfi --version outputs SATySFi version vm1.0z-****-g**** because tags v0.0.1, v0.0.2, and v0.0.3 are lightweight tags (How about using annotated tags for releases? #125). vm1.0z is an annotated tag for old Macrodown. So this is not a bug of this PR.
  • This is why I made this PR as a draft PR.
• This PR uses dune subst, which is documented here.
• The version string is properly replaced while running opam pin add, opam reinstall, or dune-release. In contrast, simple make or dune build doesn't replace it, and show %%VERSION%% for the version string. This is intended; I think the version string is confusing and not needed for the development period. If needed, use opam pin add.
• It is still under discussion how to handle versions by Dune ([RFC] How to handle versions ocaml/dune#880, Watermaking in dune build ocaml/dune#1539). Although I believe my method is better for SATySFi to handle versions, it will be worth reading those issues for future possible changes of Dune.

[nekketsuuu]

#125 is resolved and this pull req is now ready for review :)

[na4zagin3]

I'm curious. Why is this line executed only when the package is pinned, but not when a non-pinned version is being installed?

[na4zagin3]

I confirmed %%VERSION%% was not substituted when it was installed as a non-pinned package.

# Adding a package pointing to `git+https://github.com/nekketsuuu/SATySFi.git#68f8de124503634b05608f993b693dcf792d437b` to a local repository
$ opam install satysfi
$ satysfi --version
  SATySFi version %%VERSION%%

[nekketsuuu]

Please read #167 (comment)

This is intended; I think the version string is confusing and not needed for the development period. If needed, use opam pin add.

[na4zagin3]

Oops, Ioverlooked the paragraph. Sorry. So, this PR changes the release process as well: dune-release tag instead of git tag -a. It will be helpful if the new release process is explicitly described somewhere in the repo. Just my two cents.

[nekketsuuu]

No, this pull request doesn't change the release process of SATySFi. Just running git tag -a is enough.

[nekketsuuu]

Then it's out of scope of this pull request. I don't intend to change the way to release a new version. dune-release is not fit to current SATySFi.

[na4zagin3]

It is a consequence of this PR, which changes how SATySFi should be released.

As OPAM repos prefers a source tarball in url section rather than source repos (especially, the official OPAM repo prohibits source repos there), there are only two ways to substitute watermarks:

• Release a prepared distribution, in other words, source code preprocessed by dune-subst;
• Or upload a OPAM file which has a line like ["find" "." "-iname" "*.ml" "-exec" "sed" "-i.bak" "-e" "s/%%VERSION%%/v0.0.6/" "{}" ";"] instead of ["dune" "subst"] {pinned}.

Do you think “dune-release is not fit to current SATySFi” because it automatically attempts to release SATySFi to GitHub and to send a PR to the official OPAM repository?

I edited my previous comment with dune-release distrib that only generates a prepared distribution. Does that make sense to you?

[na4zagin3]

Hmm, even though it is a consequence, it can be handled by another issue/PR. You're right. Shall I file one?

[na4zagin3]

I filed #237 since I don't want to block you on this. Today I learned a lot. Thank you for a fruitful discussion!

[nekketsuuu]

I don't think this pull req changes the current release process, though.... I commented my opinion to that issue #237 (comment). Let's continue this discussion there.

[nekketsuuu]

It turns out by @na4zagin3 that this pull req removes a concrete version string from assets for a git tag, which is currently automatically created by GitHub (e.g. https://github.com/gfngfn/SATySFi/releases/tag/v0.0.5).

There are three ways to handle this issue.

• Don't worry about this change. It's completely OK if %%VERSION%% is remained in the assets. SATySFi itself never uses them.
• Change the release process of SATySFi. For example, use dune-release to replace %%VERSION%% in the assets.
• Close this pull req without merging.

@gfngfn Which resolution do you prefer? Any method is fine with me. Since you are responsible for releasing new versions of SATySFi, you can choose how to handle this issue =)

[na4zagin3]

@gfngfn FYI, if you chose the second option, there would be two methods:

with dune-release distrib

After pushing an annotated-tag to GitHub as usual, run dune-release distrib and manually register the prepared tarball. I wrote this down at #237

with dune-release

After adding an annotated-tag, run dune-release to upload the tag and the prepared tarball to SATySFi repo in GitHub, then abort registering SATySFi to the officlan OPAM repo.

[na4zagin3]

BTW, why not use %%VERSION_NUM%% rather than %%VERSION%%? Is it intended to report the version with v prefix (e.g., v0.0.5)?