path option in repository can mess with git tags

[ghivert]

When adding a path in repository in gleam.toml, when there's multiple packages in the repo, their versions can go out of sync.

Let's take an example:

• There's a package foo, located in repo/foo, in version 1.0.0.
• There's a package bar, located in repo/bar in version 1.1.0.
• When you generate documentation, all generated paths expect to find a tag in the git repo, and the path refers the tag.
  For foo, it will be https://.../v1.0.0/foo/src/module.gleam. For bar, it will be https://.../v1.1.0/bar/src/module.gleam.
• Tags in your git repo can be not synchronized, because sometimes you just cannot properly tag the repo for every version of every packages.

A solution would be to use the same version number for every packages. Every time a package version bumps, bump the other packages to the same version, and republish everything. That way, all tags will always be true.
However, it's more work for the maintainer.

One solution could be to point to a commit in the repo, instead of a tag.

---

The problem can be seen in the Sketch documentation at the moment of writing. Sketch is working, while sketch_lustre is not working.

[richard-viney]

Ah, when I implemented this a few weeks ago I was only thinking of the situation where everything was versioned in sync, hence didn't consider this case.

What about allowing the tag used in the doc links to be prefixed? So instead of v1.1.0 it would be foo-v1.0.0, that way you'd have a unique tag for each package version in a monorepo, so doc links will always work. You'd end up with more tags, but perhaps they're useful to have as those packages/versions do exist in the repo.

I think I initially prefer sticking with using tags as opposed to a commit hash, but let's see what others think.

[ghivert]

Hey, thanks for the answer!

I thought about it too, but it means in gleam.toml, we'll have some versions like foo-v1.0.0, because it will be the version published on Hex. Unfortunately it breaks the intents of semver in the first place.

I have no idea what is best. I was just proposing a solution, but I'd happily accept anything better.

[lpil]

I think we'd keep the version the same and have a way to specify some sort of tag prefix or tag pattern in the config, which would be used when rendering the paths and also when reminding the publisher to add a tag.