Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: document protocol versioning policy #56

Closed
wants to merge 1 commit into from
Closed

Conversation

aqrln
Copy link
Member

@aqrln aqrln commented Feb 6, 2017

In order to communicate with developers of alternative implementations and be reasonable about compatibility, we need to assign versions to the protocol too. This PR documents the protocol versioning policy (see details in the changed file).

According to this proposal, e.g., the current version of the protocol is 0.5 and the next one, if #54 lands, is 0.7.

@tshemsedinov, @belochub, do you agree with this proposal or you have other ideas about how we must assign versions to the protocol?


Protocol versions are bound to the first version of the `metarhia-jstp` package
that implements the specific version of the JSTP protocol. When the package
reaches 1.0.0, the protocol version will unconditionally bumped to 1.0.0 too,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably missing "be" after "will".

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I will update the commit in a moment.

Copy link
Member

@belochub belochub left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@aqrln
Copy link
Member Author

aqrln commented Feb 10, 2017

@tshemsedinov still waiting for you to review the proposal.

@tshemsedinov
Copy link
Member

Does it mean that protocol version will be equal to package version after 1.x?

@aqrln
Copy link
Member Author

aqrln commented Feb 10, 2017

@tshemsedinov to the first version of the package that introduced the changes found in this version of protocol, to be exact. Version 1.0.0 is a special one in one case: if package version 1.0 introduces no changes to protocol since, for example, version 0.9, then as soon as package version 1.0 is released, the protocol version is bumped to 1.0 anyway, just the specification is identical for protocol versions 0.9 and 1.0. The reason is that when we release the first stable version of the package, we want the protocol version to indicate that it is stable too, and vice versa, before until we have released the first stable version of the package, we cannot guarantee that the protocol is already stable since some changes in functionality require changes in the protocol

@aqrln
Copy link
Member Author

aqrln commented Feb 10, 2017

@tshemsedinov alternatively, the protocol can be semantically versioned by itself, independently of this package, as soon as we reach 1.0.0.

@belochub
Copy link
Member

@aqrln, in my opinion, alternative option to version protocol by itself is better if we are going to create formal specification of the protocol (which I hope we will).

@aqrln
Copy link
Member Author

aqrln commented Feb 10, 2017

@belochub yeah, after some thinking about it I think I would prefer the mixed approach:

  1. Before we reach 1.0, versions of the protocol are better to be bound to package versions. It would be nice to have it versioned independently, but it's too late to do it, since we haven't been versioning it from the beginning and we have made changes to the specification multiple times. I would not opt for backdating with assigning versions to what was done in the past.

  2. As soon as we reach 1.0 in the package, we take this as the starting point, assign the version 1.0 to the protocol and have its specification versioned with semver independently of the package.

@tshemsedinov, what do you think about it?

@tshemsedinov
Copy link
Member

Great

@aqrln
Copy link
Member Author

aqrln commented Feb 11, 2017

I've just updated the commit so that the document reflects the consensus of the discussion.

@belochub, @tshemsedinov, please check it out and say if it LGTY.


Before the package reaches version 1.0.0, the protocol version is bound to the
first version of the `metarhia-jstp` package that implements the specific
specification of the protocol. It would be nice to have it versioned
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe avoid phrase "specific specification"?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@belochub reworded the sentence for clarity and to be more stylistically correct.

In order to communicate with developers of alternative implementations
and be reasonable about compatibility, we need to assign versions to
the protocol too. This commit documents the protocol versioning policy.
Copy link
Member

@belochub belochub left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

aqrln added a commit that referenced this pull request Feb 11, 2017
In order to communicate with developers of alternative implementations
and be reasonable about compatibility, we need to assign versions to
the protocol too. This commit documents the protocol versioning policy.

PR-URL: #56
@aqrln
Copy link
Member Author

aqrln commented Feb 11, 2017

Landed in 51c763f.

@aqrln aqrln closed this Feb 11, 2017
@aqrln aqrln deleted the protocol-versioning branch February 11, 2017 15:37
aqrln added a commit that referenced this pull request Feb 20, 2017
In order to communicate with developers of alternative implementations
and be reasonable about compatibility, we need to assign versions to
the protocol too. This commit documents the protocol versioning policy.

PR-URL: #56
@aqrln aqrln mentioned this pull request Feb 20, 2017
aqrln added a commit that referenced this pull request Feb 20, 2017
In order to communicate with developers of alternative implementations
and be reasonable about compatibility, we need to assign versions to
the protocol too. This commit documents the protocol versioning policy.

PR-URL: #56
aqrln added a commit that referenced this pull request Apr 2, 2017
In order to communicate with developers of alternative implementations
and be reasonable about compatibility, we need to assign versions to
the protocol too. This commit documents the protocol versioning policy.

PR-URL: #56
aqrln added a commit that referenced this pull request Apr 2, 2017
In order to communicate with developers of alternative implementations
and be reasonable about compatibility, we need to assign versions to
the protocol too. This commit documents the protocol versioning policy.

PR-URL: #56
aqrln added a commit that referenced this pull request Apr 3, 2017
In order to communicate with developers of alternative implementations
and be reasonable about compatibility, we need to assign versions to
the protocol too. This commit documents the protocol versioning policy.

PR-URL: #56
@aqrln aqrln mentioned this pull request Apr 3, 2017
belochub pushed a commit that referenced this pull request Jan 22, 2018
In order to communicate with developers of alternative implementations
and be reasonable about compatibility, we need to assign versions to
the protocol too. This commit documents the protocol versioning policy.

PR-URL: #56
belochub pushed a commit that referenced this pull request Jan 22, 2018
In order to communicate with developers of alternative implementations
and be reasonable about compatibility, we need to assign versions to
the protocol too. This commit documents the protocol versioning policy.

PR-URL: #56
@belochub belochub mentioned this pull request Jan 22, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants