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.

[josecelano]

Hi @WarmBeer @WarmBeer,

I have created a workflow to publish a crate for one of my side projects. You can see the workflow here.

I wanted to create a PR to publish a tracker crate automatically when we release a new version, but there are some limitations with crates.io tokens.

1. There are no organizations or namescapes.
2. You can only sign up with a GitHub account.
3. They do not have scoped tokens. See: https://github.com/rust-lang/rfcs/blob/master/text/2947-crates-io-token-scopes.md

So, basically, we were going to use a @WarmBeer's personal token to publish the tracker, but if we do so, any maintainer who has access to the token can publish any of the @WarmBeer's crates.

The only way to avoid that problem could be to create a new GitHub account for the organization and use that account for crates.io. Even in that case, we reduce the scope only to all organization projects. Any maintainer with access to the token could publish any crates linked to the new crates.io account.

For the time being, I think we can publish manually.

@WarmBeer maybe you can do it with the current version of all the Turrust packages so at least we can reserve the name.

[josecelano]

@da2ce7 suggested using a fork to publish new releases on crates.io and also on dockerhub. For the time being, I think we could:

Version 1

• Add a workflow to publish the crate
• Use an env var to enable the workflow ENABLE_PUBLISHING_CRATE. It could be disabled in this repo.
• The crate's owners (@da2ce7, @WarmBeer and @josecelano) can fork this repo and enable the workflow on the fork.

When we one to publish a new crate version, any of us can

• Enable the workflow on their fork.
• Sync their fork from this repo.
• Push the tag to the fork. The workflow will use their crate.io's token to publish the new version.

That would be the way to do it manually. There are some extra benefits of doing that instead of doing it on your computer:

• We have a public log for who and when the release was done.
• We can add some extra tasks like running tests, etcetera.

Version 2 (completely automatically)

If we want to do it completely automatically, we need to use something like this:

https://github.com/marketplace/actions/upstream-sync#sample-workflow

We can create a "release" repo which only contains a workflow that syncs the upstream repo (this repo) with the forked version (the repo of the "publisher"). I guess we can also push tags and trigger the workflow to publish de release on the fork.

I'm going to implement the first version, for the time being, for both:

• Publishing the crate
• Publishing the docker image

[josecelano]

I think we can close this. We are already publishing the crate and we have defined a release process.