Set Version Number in Cargo.toml

[jasongrlicky]

Just updates Cargo.toml and README to show the current version number.

Of course, both of these locations should be updated again the next time a release is made for this crate on Crates.io - this pull request is just intended to get the process started.

The reason for this change is not just consistency - having the crate uploaded to Crates.io without a version number in the Cargo.toml makes patching the dependency not work as expected, making it harder to contribute to this repo.

Thank you! 🙏

[chris-zen]

@jasongrlicky this PR would break the CI process that updates the version from the git tag (See this). I'm wondering if we could solve the patching problem in another way, while keeping automatic version from tags.

[jasongrlicky]

Ah, that makes sense!

I'm not very familiar with CI in general, so I'll have to read up on that and see what our options are. I'm hopeful that there is an easy solution out there, since I know a lot of Rust crates use CI, but still have version numbers in their Cargo.tomls.

[chris-zen]

Hi @jasongrlicky, thinking about your comments:

having the crate uploaded to Crates.io without a version number in the Cargo.toml makes patching the dependency not work as expected

I think this is not a problem, because I replace the 0.0.0 version with the actual tag (see this, this and this) before publishing the package to crates.io. Is there anything else I missed ? Can I close this PR ?

[jasongrlicky]

Hey @chris-zen! You're right that the patching issue is not a problem on the Crates.io side - since as you mentioned, the version number is replaced in Cargo.toml before a new version is published.

Unfortunately, the problem arises when making changes to the coremidi crate in the context of a project that depends on it. This can be useful for testing changes or debugging issues in a real-life context. In the simplest case, the workflow is as follows:

1. Clone a local version of this repo, and make some changes.
2. To evaluate the changes in the context of the dependent project, we need to tell Cargo to use the local version instead of the Crates.io version, so add the following to that project's Cargo.toml:

[dependencies]
coremidi = "0.4.0"

[patch.crates-io]
coremidi = { path = '/path/to/coremidi' }

3. Build the project, and Cargo should swap out the local version of coremidi for the version published on Crates.io.

The issue is that when the local repo for coremidi has a 0.0.0 version number, Cargo doesn't actually swap out the versions, and instead shows a warning:

warning: Patch `coremidi v0.0.0 (/path/to/coremidi)` was not used in the crate graph.

Because the local repo has a version number that is semver-incompatible version with 0.4.0, Cargo sees them as different dependencies, and thus doesn't understand that coremidi v0.4.0 actually needs to be patched.

The workarounds on the user-side are either to temporarily replace 0.4.0 with 0.0.0 in the dependent project's Cargo.toml or to replace 0.0.0 with 0.4.0 in the local coremidi's Cargo.toml. And then to remember to switch it back when un-patching, of course.

So in the simplest case, it's minor a speed-bump to contributing to the crate or integrating it into a project. But in a more complex situation (patching the dependency in projects that depend on projects that depend on coremidi, etc), or if doing a git bisect, it becomes really annoying to manage.

It seems to me that the fundamental problem here is that the entire Cargo & Crates.io ecosystem expect these two version values (the version on Crates.io & the version in the Cargo.toml) to be the same. The fact that Cargo patching doesn't work properly is just the first symptom of this that we've seen - I'm sure that more issues related to not having a real version number in Cargo.toml will arise as Cargo & Crates.io continue to be developed.

So I'm planning to spend some time this week learning about Travis, making sure I understand your crate publishing workflow and CI requirements, and seeing how crates usually handle these scenarios. My goal is to amend this PR with changes to the way CI & publishing are done that are compatible with your current workflows, but also avoid all the hackery required to switch out the 0.0.0 version number. It might not be possible, but I'd love to give it a shot. If you wouldn't mind keeping the PR open while I learn this stuff, that would be super helpful to keep the discussion moving!

Thanks so much 🙏

[chris-zen]

That has been addressed already.