search

RayMarch / shame

A shader EDSL for writing render and compute pipelines in rust
Apache License 2.0
252 stars 5 forks source link

Publish a crate? #1

Open brandon-reinhart opened 2 years ago

brandon-reinhart commented 2 years ago

I couldn't find a published crate for shame, but maybe it's under an unexpected name? Or is there some other plan for distribution or this just hasn't been done yet?

RayMarch commented 2 years ago

thx for asking, it's not on crates.io so far. For now you'd have to write 

shame = { git = "https://github.com/RayMarch/shame.git", tag = "v1.0.1" }

into your Cargo.toml, I haven't had the time yet to read up on crates.io publishing and also getting the docs on docs.rs.

bddap commented 2 years ago

Publishing to crates-io is pretty easy in my experience. docs: https://doc.rust-lang.org/cargo/commands/cargo-publish.html

Once published, docs will get built automatically and posted on docs.rs.

You may have already seen this, but if you want some expert guidance on writing rust apis check out the excellent rust api guidelines.

Couple more things you might want to consider before publishing

  1. Rust crates use semantic versioning. Once you publish a version "1.0.0" users will expect the api not to change in any backwards-incompatible way except when updating to version "2.*.*". Since this crate is new, I suggest starting at "0.1.0" and only publishing "1.0.0" when you are sure the api is stable. Some crates take years to reach "1.0.0". There's no rush :)
  2. Rust comes with standard code formatter called rustfmt. Rustfmt will make it easier for others to read an contribute to your project. To use it, run cargo fmt at the root of the repository. It's a high quality formatter; it won't break any of your code. The easiest time to start using rustfmt is when a project is new.
  3. Did you know cargo can review your code for you? Try running cargo clippy. It gives very good advice.

By the way, This library looks super cool. I've been wanting something like this for a while. I look forward to trying it out.

RayMarch commented 2 years ago

Thank you for the recommendations, i have actually not seen those api recommendations yet! I really should have run rustfmt before publishing, thats my bad.

Do you recommend turning the version number back to below 1.0.0? I heard online that theres a certain "1.0.0 shyness" in the community. I am also unsure about how to handle the git version tag. Should all the crates in the repository always match the git tag, or should the all crates each have different version numbers and be bumped separately based on the changes?

Thx for taking interest in the library. Make sure to post your experiences/suggestions in the community discord, i'd love to hear them.

bddap commented 2 years ago

Do you recommend turning the version number back to below 1.0.0? I heard online that theres a certain "1.0.0 shyness" in the community.

I can see why someone might say that. Lot's of widely-used pre "1.0.0" crates out in the ecosystem. Maybe it's not such a bad thing though; it shows that those crate authors are serious about semver compliance. I do recommend changing the version number for shame to something below "1.0.0". The way I see it, your options with respect to versioning are:

I am of course assuming you'll want to be able to make breaking changes. It would be pretty impressive if you designed the api perfectly first try :)

I am also unsure about how to handle the git version tag. Should all the crates in the repository always match the git tag, or should the all crates each have different version numbers and be bumped separately based on the changes?

Not sure if there is a standard way of doing this. I usually keep all crates in the workspace at the same version and tag that version in git. Makes it easy to reason about. (fyi there is tool that can set the versions of all crates in the workspace cargo set-version --workspace '0.1.0')

bddap commented 2 years ago

Oh, please don't let my suggestions stop you from pushing an initial release. The first version doesn't need perfect formatting, etc. shame is ready as-is. Not trying to gatekeep.

RayMarch commented 2 years ago

oh don't worry, i do appreciate the guidance! The reason theres not much visible progress right now is because i'm trying to implement for loops and break/continue statements, which touch a bunch of code. After that is merged i'll run rustfmt and think more about the semver situation.

The whole shame_graph crate is kind of like an internal api that shame uses and wraps static rust typing around. During development it became clear that shame_graph is pretty much necessary to enable users to properly write generic shame code, because otherwise the trait bound overhead gets out of hand (see bounds like CanBeMultiplied). So on the one hand i want shame_graph to be a quickly iterable internal api, on the other hand its really nice for users to have access to it in the odd case where they need it. This makes me not quite sure how to deal with the semver of shame_graph.