Publish it on crates.io

[josecelano]

Wouldn't it be useful to publish it on https://crates.io/?

I would like to write more documentation for the package. For example, for API endpoints like this:

If we do that, we can automatically have online documentation on https://docs.rs/.

If for some reason, we do not want to publish it yet, we could deploy the documentation to GitHub Pages.

[josecelano]

I would also like to add more info for developers about how to set up your local env to start contributing to this repo. Maybe for those "tutorials", we could use markdown in the docs folder with mkdocs (or without mkdocs).

[mickvandijke]

I haven't looked into this yet, but I noticed that most rust projects have a https://crates.io/ page, so it would probably be great for our project too :)

[josecelano]

I haven't looked into this yet, but I noticed that most rust projects have a https://crates.io/ page, so it would probably be great for our project too :)

OK, we can add one more job in the CI workflow to publish it when we release a new version.

[da2ce7]

@josecelano @WarmBeer

I think that it is a good idea to publish to to https://crates.io/ . I think that we should consider tagging our releases as "beta", so that others don't get the idea we think that our code is production-ready. (even if it is already used in production somewhere)...

[josecelano]

hi @WarmBeer @da2ce7

What we should do once we start publishing the package:

1. Include the version field in the Cargo.toml

[package]
name = "hello_world" # the name of the package
version = "0.1.0"    # the current version, obeying semver
authors = ["[email protected]"]

More info: https://rurust.github.io/cargo-docs-ru/manifest.html#the-version-field

2. Follow semver rules:

• https://rurust.github.io/cargo-docs-ru/crates-io.html#publishing-a-new-version-of-an-existing-crate

• https://rurust.github.io/cargo-docs-ru/manifest.html#the-version-field

• Before you reach 1.0.0, anything goes.

• After 1.0.0, only make breaking changes when you increment the major version. In Rust, breaking changes include adding fields to structs or variants to enums. Don’t break the build.

• After 1.0.0, don’t add any new public API (no new pub anything) in tiny versions. Always increment the minor version if you add any new pub structs, traits, fields, types, functions, methods or anything else.

• Use version numbers with three numeric parts such as 1.0.0 rather than 1.0.

For semantic versioning (https://semver.org/#semantic-versioning-specification-semver):

• Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

• Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes.

Since we do not consider stable the current release, I suppose we should have used 0.y.z for all the previous releases.

We could either: delete all previous releases or try to keep that information somehow.

I proposed to rename current tags like this:

• 2.0.0 -> 0.2.0
• 2.0.1 -> 0.2.1
• 2.2.0 -> 0.2.20
• 2.3.0 -> 0.2.30
• 2.3.1 -> 0.2.31

I suppose we can just do this for each tag:

• Create the new corresponding lightweight tag.
• Create a new release for the new tag. Copy&pPaste release text. Link to the new tag.
• Remove the old release.

We could also create a CHANGELOG file and delete all the releases. But It would be weird if we did not use it anymore.

We can also just remove all the releases. It probably does not make sense for anyone to go back to a previous version, especially because we are not maintaining old versions yet.

I would say we can just save all the previous releases info in a file (OLD_TEST_RELEASES.md) and just delete them. And then release the 0.1.0 version.

[mickvandijke]

I'm not sure what the best practice is in this case. But I do prefer keeping the old tags and version numbers as they are and continue on a new major release: 3.0.0 and add the beta tag (like @da2ce7 proposed) for untested releases. Eg: 3.0.0-beta

[josecelano]

I'm not sure what the best practice is in this case. But I do prefer keeping the old tags and version numbers as they are and continue on a new major release: 3.0.0 and add the beta tag (like @da2ce7 proposed) for untested releases. Eg: 3.0.0-beta

That's fine for me. After all, we have not defined what we consider a ready-for-production app. And we have not even published an official package on crates.io. Maybe we should simply write down a list of things we consider essential in order to use the app in production, and they are still missing.

I can start. For me, essential things are:

• Following strictly semver conventions,so people can rely on what we tag.
• Maintain service branches for versions.

And nice things to have:

• Good test coverage to avoid regression.
• A roadmap to organize issues (especially those that require breaking changes).

Nice things but not strictly necessary:

• Extensive documentation

With those requirements, we could publish 3.0.0-beta and 3.0.0 in a couple of weeks.

[da2ce7]

With those requirements, we could publish 3.0.0-beta and 3.0.0 in a couple of weeks.

We can have 3.0.0-beta and 3.0.0-beta.2 and so on.