Revision control, start to tag spec releases (...)

[dexX7]

Mentioned a few times, but given the recent change of 51: New Property Creation via Crowdsale with Variable number of Tokens there is a new example why this is needed.

We are going to replace version 0 of this transaction type with version 1, but the updated version of the spec only includes a description of version 1. Because version 0 transactions exist nevertheless I think there should be a reference to version 0 somewhere.

The easiest way to accomplish this is probably to use git tags/releases to assign version numbers similar to those we already use in the changelog to specific commits. This allows to lookup historical versions of the specification.

A reference to an older version of a transaction type could be included by an one-liner like "for version 0 of this transaction, see 0.4.5.7 tx ...." with a link to this specific release/version.

[ghost]

This is a great idea, dexX, as usual. If you know where in history to make the tags, I can go through and do them on my branch, or, if someone is willing to go through history and figure that out, the git command to make a tag at a specific commit is as simple as:

git checkout (hash)

git tag -s v0-tx00 -m "Simple send version 0"

This creates a signed tag off your current checkout

[dexX7]

Ah, I never did this, but it sounds simple. I'd suggest to tag the commits according to the version numbers mentioned in the changelog and then add a reference to older transaction versions instead of labeling commits directly with transaction types and versions. What do you think?

[ghost]

Hm, how do you mean add a ref? via the commit message or some other way? Everything else sounds good, just need a little clarification on what you meant

[dexX7]

I meant a link/reference to the release directly in the specification next to the description of the transaction, e.g.: something like "the description of version 0 of this transaction can be found in v0.x.x.x" where v0.x.x.x is a link to the release which was tagged with that version number.

[marv-engine]

I like this idea. I like it even more if it will allow us to get rid of our w.x.y.z doc version numbers.

[dexX7]

Hmm.. could use commit hashes, e.g.: bae58683a6

[marv-engine]

We need a way that works with simultaneous PRs - so multiple PRs don't choose the same next version number.

[dexX7]

That's actually quite tricky I think. Say we start to use commit hashes - which are not really human friendly - the problem of version number allocation is solved, but what still ramains is the problem of an ordered changelog.

@faizkhan00: does a commit hash change with the content of the commit? If this is the case, we can drop the commit hash idea right now, because it's impossible to say "this version uses hash xyz", if "xyz" changes after including this statement.

[dexX7]

Hmm.. I tested the release tagging feature:

• https://github.com/dexX7/spec/releases
• https://github.com/dexX7/spec/tags

Which worked fine via git checkout (commithash) + git tag -s v0.0.0.0 -m "update notes" or git tag -a v0.0.0.0 -m "not GPG signed".

But it looks like the release notes that can be defined under /tags (web) are another feature. I'm a bit confused about this, because I don't see the relation right now, but I'll do some research.

While going back in history there was often the case where something was pushed, say by marv, and the next commit merged the previous one, usually done by JR. What would be the best practise here? Tag the first commit or the merged one? I noticed also the dates in the changelog often didn't match - which is obvious, because it's the date of writing, but not of merging.

GPG signing didn't work via the mingw bash, but was fine via cmd -- I'm using Windows right now with Kleopatra. Click here to get my GPG key.

So what's the plan? Even though I'm not sure, if this is the utmost best solution, I think we should really start to adopt this in some way.

@LOLLOLOOLOL: ping you're probably one of the guys who has some good ideas related to this, too.

[LOLLOLOOLOL]

The more broad issue here is that for a given transaction we can't determine if it was valid at the time of its first confirmation, or necessarily what rules should be applied to it. I have ideas of how I would like to solve this more broad issue, however they're a bit on the "fringe" right now and probably not applicable to this discussion at the moment.

Why not just hex encode the definition, have the Exodus address embed the definition in the blockchain? This allows reference by txid (which everybody is familiar with) and implicitly defines a range of blocks for which that definition is applicable. It doesn't have to be in any special format (for the time being), just with all the critical information. Then add an appendix, or some other document that lists tx, version, definition, link to commit (which could very well use the tags/releases features, +1 for that), and txid hash. This is an idea that isn't necessarily the best, but addresses the issue here, and moves towards the right direction.

Maybe this is idealistic of me, but what platform is reasonable to support the specification a project of this nature? GitHub is very convenient for it, however GitHub may prove to be a transitory platform in the history of Mastercoin.

EDIT: Also, revision # = block height.

[dexX7]

Not all changes to this document have an impact on transaction verification, for example the information about transaction costs. There is no short version related to verification and sadly, at least at the moment, relevant information is spread over the whole document. Each multisig output provides space for 60 byte data (1x sender pubkey, 2x data), so storing more than a few words likely creates huge transactions. Not sure, if this is really necessay, or if it would be sufficient to store a commit hash for example instead, as proof of publication and announcement of "hey guys, here is an update, check out the new version of the spec". At least I hope the access to the Exodus wallet is not easily reached, so security might have some weight here and it may even be more reasonable to use another wallet for this purpose.

Long story short: it looks like everyone is in consensus about using the tag/release feature. I'm not sure how to address the situation where two pull requests are pending which might compete about the next version number, but I think we can communicate before release to sort this out.

[LOLLOLOOLOL]

Ah, my focus was limited to transaction revisions.

The spec currently serves many more purposes than as a specification. IMO, no revision references needed for things like transaction costs, or any other non technical section. As far as I'm concerned they should be removed and placed elsewhere. This allows a clear separation between the things that need revision control and the "fluff," makes the spec more spec like, and makes the entire thing easier to maintain.

Should changes that don't have an impact on transaction verification require strict revision references?

[ghost]

@faizkhan00: does a commit hash change with the content of the commit? If this is the case, we can drop the commit hash idea right now, because it's impossible to say "this version uses hash xyz", if "xyz" changes after including this statement.

Apologies, I should have followed up here:

Yes, a commit hash changes if you recommit/change the content, since all a hash really is is a SHA-1 of all the prior commits

[LOLLOLOOLOL]

I propose that we use the master as a staging branch to which numerous commits can be made before requiring a new version number - doesn't really matter by what metric the new number is deemed necessary.

This way we can change the version number, create a branch named with the version number, and then tag that commit as a release. The idea here is to define discrete versions (releases) of the specification that MP wallets should implement in order to stay in consensus with the reference client. Ideally a new spec release would coincide with a new release of the reference client so that a client release can be directly associated with a specification version.

We can further enhance this by defining the block number (in the future) at which the new spec release goes into effect. This gives us a rudimentary mechanism by which we can associate a set of MP transactions with the specification version that defines them.

This resolves the issue with pull requests with conflicting version numbers, and enables us to refer to a transactions version history by referencing releases rather than commits.

It'd also be possible to do away with the traditional version numbers by referring to hashes, as previously mentioned. We can regain an ordered changelog by concatenating the hash of a commit with the block height at which that release is considered "in effect." I think the only thing we lose here, besides readability, is the ability to indicate major/minor/etc. versions.

does a commit hash change with the content of the commit? If this is the case, we can drop the commit hash idea right now, because it's impossible to say "this version uses hash xyz", if "xyz" changes after including this statement.

I disagree. If a spec version changes a transaction version it should be mentioned in the changelog, however only needs to be referenced in subsequent versions. Anyway, the reference could immediately be committed to the master branch in which case we haven't lost much at all. :)

[dexX7]

Unrelated to what initially lead to open this issue, namely that older transaction versions are "lost" while still active on a protocol level (which seems to have created some confusion in #240 and in another issue), I recently stumbled upon a concept called Semantic Versioning 2.0.0 (semver.org):

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

A few examples transferred to our context (based on my interpretation):

Major: something completely different, like a new transaction encoding scheme*
Minor: the step from tx 20, version 0 to tx 20, version 1 where an action field was appended*
Patch: spelling, style-changes

It's tricky for me to differentiate between major and minor in this context, because every new transaction type and so on has significant implications and if the rule would be "it's major, if it breaks consensus between new version and old version", then we'd probably end up with many major increments, while another approach could be that adding a new transaction type might still be considererd as minor change, if the view of world of a client which uses an older version of the spec results in a subset of the view based on the new version.

Rephrased: what I'm thinking about was the case where smart properties were introduced and available via Masterchest, while not adopted by masterchain.info. The later made it impossible to fetch SP related data on masterchain.info, but didn't result in absurdly wrong balances or whatsoever of the information that were shown on masterchain.info.

To cut it down:

• I think we must find a way to keep information about older transaction versions nearby
• I think we should apply some form of versioning that isn't completely arbitrary (i.e. jumps from 0.4 to 0.4.5), whether that is semantic or purely based on commit hash references
• I think we should start to tag the spec and use the "tag", "release" functionality of GitHub