[doc] Update CONTRIBUTING about PR and versions

[woshilapin]

Some help about why and how we update versions of Cargo.toml files in the Pull Request.

[antoine-de]

it feels a bit awkward to bump the version if the previous has not been released no?
I’d understand it if this was continuously released but it does not seems the case.
Isn’t it better to do it at release time ?

[woshilapin]

it feels a bit awkward to bump the version if the previous has not been released no?

Yes, and maybe it's not clear that this is exactly what I'm trying to explain here, but you should not bump the version if it's already alright.

Examples:

1. Version 1.0.0 is already released and Cargo.toml contains 1.0.0
2. Alice makes a bug fix, she bumps the Cargo.toml to 1.0.1
3. Bob makes another bug fix; he sees 1.0.1 is not released yet, so he doesn't need to make a change
4. Carl makes a breaking change, he bumps to 2.0.0
5. Donald makes a new feature; he sees there is already a major bump, so it does not need to bump the version.

And notice how at each step, we could have published a release right away.

Isn’t it better to do it at release time ?

The pain to do that at release time is that the owner of the release doesn't necessarily know the details of each PR (is it a breaking change or not?), and would need to either do a new PR only to bump a version (that's a shame for just a version bump) or push a new commit directly to master (not a fan of pushing commits directly to master and actually, master might just be protected against push).

[antoine-de]

hum isn’t it difficult for Bob to know that there has not been a release?

[woshilapin]

https://crates.io/crates/transit_model/versions should be enough.

[pbougue]

IMO, instruct to compare with crates.io is the clearest you can do here, I'd add it to the sentence :)

[woshilapin]

I've introduced it as a link, tell me if that's fine.

[pbougue]

IMO, instruct to compare with crates.io is the clearest you can do here, I'd add it to the sentence :)

[datanel]

I think updating the version should not be something mandatory for an external contributor (not from the team). he should not have to think about it systematically but the team does.

[woshilapin]

I think updating the version should not be something mandatory for an external contributor (not from the team). he should not have to think about it systematically but the team does.

We might mention it if the contributor forget, but I would like to avoid as much as possible PR exclusively for bumping. Said differently, I'm totally fine if an external contributor forget to do it (we too forget about it sometimes), but yet, I'd like it to be documented, and we will remind to the contributor to do it before merging the PR.

[datanel]

My point is we must not force the developer to always change the version if needed. If he wants to bump the version it's ok but it's the responsability of the team to think about if when releasing.

[woshilapin]

My point is we must not force the developer to always change the version if needed. If he wants to bump the version it's ok but it's the responsability of the team to think about if when releasing.

I'd rather document our process, and be OK with an external contributor forgetting about it, than not documenting our processes.

[woshilapin]

My point is we must not force the developer to always change the version if needed. If he wants to bump the version it's ok but it's the responsability of the team to think about if when releasing.

I've added commit a42eca5 to smooth the tone a little. The idea being that we might even propose a PR on top of the contributor's branch to help him do it. Or help him decide which version's bump should be done. In general, we do not have a lot of external contributors, so I'd say we will be extremely careful to please them and help them as much as possible.