Release process documentation

[na4zagin3]

https://github.com/gfngfn/SATySFi/pull/167 will (or did) change how SATySFi should be released.

Why not adding notes on the release process to somewhere, for example, a new section in the README, or a new file?

Release Process

SATySFi uses dune-subst to substitute watermarks. Therefore it must be released in the following process so that prepared distributions (e.g., satysfi-v0.0.6.tbz) are uploaded to GitHub.

$ git tag add -v <version>
$ dune-release distrib
$ git push origin <version>

After pushing the new tag, a new release. is automatically created. Then upload the file _build/satysfi-<version>.tbz to the release.

[nekketsuuu]

What do you mean by the word "release"? Currently SATySFi is released just by tagging. If this continues, pull req #167 will not change the release process, right?

Although Satyrographos, one of unofficial installation methods for SATySFi, uses custom OPAM repository, SATySFi itself currently does not. Just adding a tag is enough after #167 is merged. From my point of view, it is you who (will) change the release process (for Satyrographos...).

(Context: https://github.com/gfngfn/SATySFi/pull/167#discussion_r456769146)

[na4zagin3]

What do you mean by the word "release"?

By “release” I mean to create a “Release” (e.g., https://github.com/gfngfn/SATySFi/releases/tag/v0.0.5) in GitHub.

Currently SATySFi is released just by tagging. If this continues, pull req #167 will not change the release process, right?

Yes. That's why I filed this issue.

Here I'm proposing two points:

1. Have a document about the release process
2. Have a GitHub release provide a valid source tarball.

After merging PR #167, source tarballs automatically generated by GitHub will be silently broken. Not only Satyrographos, but every third party packaging using the tarballs (e.g., NixPkgs) will be affected.

As one of the third-party packagers, I expect a GitHub Release provides a valid source tarball (point 2.); otherwise, we need to apply a patch to substitute embedded watermarks (e.g., Adding a line like ["find" "." "-iname" "*.ml" "-exec" "sed" "-i.bak" "-e" "s/%%VERSION%%/v0.0.6/" "{}" ";"] to the OPAM file).

Regardless of whether the release process is updated (point 2.), I expect to have a documentation of the release process (point 1.) because packagers will use the tarballs by default until they find out the tarballs are not valid. Documents will help them create correct packages.

[nekketsuuu]

It makes sense. Now I agree that it may lead a problem that %%VERSION%% is remained in source code archives prepared by GitHub. Thanks for pointing that out.

To be precise, AFAIK, SATySFi doc has never said to use the source code archives to install SATySFi. So it's a fault of packaging tools if this change breaks their SATySFi.

However, it is in fact a non-mentioned change that https://github.com/gfngfn/SATySFi/pull/167 removes its concrete version string from the code archives. I'll ask gfn-san's preference. Thanks.

[na4zagin3]

It makes sense. Now I agree that it may lead a problem that %%VERSION%% is remained in source code archives prepared by GitHub. Thanks for pointing that out.

:+1:

To be precise, AFAIK, SATySFi doc has never said to use the source code archives to install SATySFi. So it's a fault of packaging tools if this change breaks their SATySFi.

The documents do not prohibit it either. As traditionally a OSS is distributed in a source tarball, it is the first choice in many package systems. SATySFi’s providing an invalid tarball without documentation will be not a fault but will be inconsiderate.

However, it is in fact a non-mentioned change that #167 removes its concrete version string from the code archives. I'll ask gfn-san's preference. Thanks.

:+1:

If gfn-san does not want to use dune-release, which may do too much, I hope it is acceptable to manually register a prepared tarball made by dune-release distrib after pushing an annotated-tag to GitHub.

[nekketsuuu]

The documents do not prohibit it either.

This is not so important. Build method using opam pin is documented and build method using a source code archive is not. That's it. In addition, historical convention should be considered separately from this statement.

If you want SATySFi to follow that convention, you should write so. I don't think it is necessary for SATySFi to follow that rule.

[na4zagin3]

The documents do not prohibit it either.

This is not so important. Build method using opam pin is documented and build method using a source code archive is not. That's it. In addition, historical convention should be considered separately from this statement.

Could you please tell me which “statement” you meant? I assume you meant this issue.

If you want SATySFi to follow that convention, you should write so. I don't think it is necessary for SATySFi to follow that rule.

Okay, I think I see your point. Let me clarify my requests here.

1. I think it’s better for SATySFi to follow the convention, but I'll support even if the project owner decides not to do. This is just a nice-to-have.
2. If it is decided to follow the convention, I'd like to suggest writing down a release process. The issue description has a proposal. (The proposal could have been split into another issue, though.) This is also a nice-to-have.
3. If it is decided not to follow the convention, I'd like to request a notice or at least hints written so that the fact SATySFi has releases in GitHub does not give misconceptions on the release process.

In my original request I summarized clause 2. and 3. as to “have a document about the release process” because a release process doc will suffice for clause 3.