search

dapphub / dapple

EVM contract system developer multitool
GNU General Public License v3.0
298 stars 59 forks source link

semantic versioning specification #199

Open mhhf opened 8 years ago

mhhf commented 8 years ago

Lets discuss the specification for the semantic versioning schema for packages here.

ghost commented 8 years ago

Exact versions must be specified in dappfiles and follow the format <major>.<minor>.<patch>.

dbrock commented 8 years ago

If we have to specify exact versions, what's the point of semantic versioning?

mhhf commented 8 years ago

Please stop me before I over engineer things!

We should make the semantics clear on what major, minor and patch mean here and if those informations are sufficient. With ethereum we deal with a unique problem space and the notion of semantics can't be copied from other spaces. Example questions could be:

Before we can define the semantics and the semantic versioning we should clarify what the distinct atomic changes, one can make to a package: e.g.:

The motivation behind this is to be able to infer information based on Versioning (e.g. pach increase => abi don't change) and based on this automatize certain aspects (e.g. trusted oracle verify the validity of version increase => automatically switch to patch increase). With such a distinction, dapple could mostly automatically handle the versioning.

dbrock commented 8 years ago

WHOA!!!!! Haha, you scared me, dude!

dbrock commented 8 years ago

The idea of semantic versioning is pretty simple, so from that perspective I think your questions can be answered quite straightforwardly...

Is it valid to change the ABI along with a patch increase?

No.

Is it valid to change the ABI along with a minor increase?

Yes, as long as it is backwards-compatible.

Is it valid to remove tests on a patch increase, or just submit additional tests?

Yes, the tests are not relevant here (but obviously all tests should pass).

Is it valid to add new objects to the dappfile on patch or minor increase?

Yes: bump the minor version.

simple redeploy (full, partial)

If the new system is identical to the old system, why are you even doing a redeploy? If to simply fix a problem, just bump the patch version. If to somehow fork into two systems, you should probably bump the major version or even register a new package altogether.

add data (contract class, tests, readme, documentation, deploy scripts)

If adding new backwards-compatible functionality, bump the minor version. If not adding any new functionality, bump the patch version.

partial remove/ change data without affecting the objects (contract classes + addresses)

If backwards-incompatible, bump major. If bug fix, bump patch. If new features, bump minor.

change contract class + redeploy without changing the abi, without changing contract class tests (e.g. add additional tests)

If backwards-incompatible, bump major. If bug fix, bump patch. If new features, bump minor.

change contract class + redeploy + change tests without changing the abi

If backwards-incompatible, bump major. If bug fix, bump patch. If new features, bump minor.

change the abi

If backwards-incompatible, bump major. Otherwise, bump minor.

add new contract class + object

Bump minor.

remove contract class + object

I presume this would be backwards-incompatible, so you'd have to bump the major.

achieved milestone (human marked)

Again: If backwards-incompatible, bump major. If bug fix, bump patch. If new features, bump minor.

mhhf commented 8 years ago

ok, sry for the over engineering

dbrock commented 8 years ago

I'm somewhat skeptical of treating semantic versioning as a foundational concept at all.

It may be the sort of "schelling point" of version number semantics right now, but I don't know how useful it actually is in practice.

ghost commented 8 years ago

@dbrock: My thoughts regarding semantic versioning are that in this case it's more useful than, say, a content hash because it works as a shorthand to convey the sort of information you mentioned in your answer to @mhhf. If I'm contemplating updating a dependency in my package, semantic versioning allows me to quickly narrow my line of inquiry based on what degree of change I'm willing to deal with.

Edit: The reason behind why we've chosen to require exact versions is because the stakes are potentially higher if a malicious change is introduced via a new version of some foundational package. While we could have something more like what NPM offers in place, I'm not sure if the convenience warrants the risk.

dbrock commented 8 years ago

The problem is that semantic versioning is subjective, so it's just a structured way for a package author to communicate (crudely) with its consumers.

There is nothing objective about semantic versioning.

But if we're not providing anything like the standard ~4.7.2 specification (or ~> 4.7.2 in Ruby notation), then I guess it becomes a little academic to debate what the version numbers "mean", if anything.

ghost commented 8 years ago

Yeah, I agree. It's not objective or anything. It's just a common convention. Crude communication, as you say, but it's better than nothing (IMO).

Part of me does like the idea of trying to make it objective and clearly defined, as @mhhf put forward. I don't particularly want to try coming up with a new versioning schema myself, though either of you are welcome to try it. The "semver" schema seems pretty well embedded in the hive mind at this point, so I'm hesitant to push anything that departs too far from it.

We could probably provide a weak version of what @mhhf proposes by redefining "backwards compatible" to mean "passes all tests from the previous version and does not mutate or remove existing function signatures", "new feature" to mean "changes the ABI and is backwards compatible", and "bug fix" if all changes in a release are backwards compatible and do not mutate the ABIs of non-test contracts.

@mhhf, what are your thoughts on this?

Edit: The validation should also only act to define a lower boundary for the version. If my version is only backwards compatible because the old version had terrible test coverage, I should be able to forcibly bump the major version number.

dbrock commented 8 years ago

Yeah, interesting line of thought!

mhhf commented 8 years ago

Don't get me wrong. I like the semver as well and also don't want to come up with something new. However from dapphubs perspective I'll have to engineer a package increment validator: a function which gets 2 packages and verify if the incremented semver is valid based on the underlaying changes (e.g. marked as invalid if abi has changed and only patch increased) I like the definition @ryepdx put forward. Will have to think about this in depth.