Tagged versions

[jake-arkinstall]

Is there a plan to start tagging versions of dbx_build_tools? If not, I'd like to propose that this be considered. If rolling release is a specific project plan, then I wonder if there are ways of getting some of the user experience from a versioned system by way of regularly updating the README.

At the moment the documentation states the following:

Real use cases should pin a commit and set the sha256.

As a way of excusing a code example that does something... bad:

http_archive(
    name = "dbx_build_tools",
    urls = ["https://github.com/dropbox/dbx_build_tools/archive/master.tar.gz"],
    strip_prefix = "dbx_build_tools-master",
)

It seems that this is a direct result of having no tagged versions, so users who just want the bleeding edge code can do the above and then fix it later once they've got comfortable. However, hermeticity isn't an afterthought, and although it is not within the remit of this project to spoon-feed newcomers to Bazel, if the real use case should do something, the documentation probably shouldn't demonstrate the 'bad' way.

Another reason for versioning is that the documentation can become outdated when code changes, and providing the version that the documentation is valid for is a nice way of preventing confusion. What is valid for master one week might be valid for master the next as a procedural restriction (stable APIs are always nice), there may come a time that a change is required that renders existing documentation incorrect. Tying the documentation to versions helps this - if a README recommends downloading version 1.2.3, one can assume that it is a good representation of version 1.2.3.

Finally, users are able to see specific changes between two minor versions, so they can keep track of how those changes impact their use of the project. This is much harder to do in a rolling approach, because there can be commits that make changes, commits that later revert them, and generally reading through vague commit messages to see what has changed can get... messy, from a user perspective.

(There is the issue of not being able to keep the SHA256 correct at exactly version X.Y.Z, so a usual approach is to remove the SHA256, tag a version, then make an additional commit with the now-known SHA256 so that the first thing a user sees when visiting the github page is a valid set of instructions to get to a reproducible result).

[benjaminp]

We probably don't have the resources to do this, unfortunately.

[jake-arkinstall]

Is the tagging the issue, or the readme maintenance? The latter can be done via PR by those interested in keeping up with the project - but on tagging it's something that needs to be done by maintainers.

[benjaminp]

Both, but it's mostly the thinking involved rather than the mechanics that's extra work. What will be the semantic meaning attached to a tag? As far as we're concerned, each commit is equal.