Purpose of 1.0 release

[jonathanfine]

I'm not clear about the purpose of this release. (By the way, I think 1.0 is much too large a number, given that all we're doing is porting the software to Python3, and previously it was 0.1.1.)

@ghickman in https://github.com/py3minepi/py3minepi/pull/54#issuecomment-59644353 wrote

We are not looking to improve legacy code for the 1.0 release.

So why the additional getHeight below?

By the way, the signature of the Minecraft constructor has changed. This surely breaks backwards compatibility.

In 6eeb804 we have

class Minecraft:
    """The main class to interact with a running instance of Minecraft Pi."""
    def __init__(self, connection):
        self.conn = connection

        self.camera = CmdCamera(connection)
        self.entity = CmdEntity(connection)
        self.player = CmdPlayer(connection)
        self.events = CmdEvents(connection)

In 9f3bfba we have

class Minecraft:
    """The main class to interact with a running instance of Minecraft Pi."""
    def __init__(self, address="localhost", port=4711):
        self._conn = Connection(address, port)

        self.camera = CmdCamera(self._conn)
        self.entity = CmdEntity(self._conn)
        self.player = CmdPlayer(self._conn)
        self.events = CmdEvents(self._conn)

        self.getHeight = self.getGroundHeight

[ghickman]

@jonathanfine – thanks for bringing this up!

I'm going to close this issue since you've raised the bulk of it in #59. I've also added that issue to the milestone for the 1.0 release so we can track progress to that release.

So why the additional getHeight below?

I suspect this is another artefact from the sprint, I've raised a new issue for it so as not to get tangled up in this one.

By the way, I think 1.0 is much too large a number

I will defer to @doismellburning to explain why SemVer is a great idea.

[jonathanfine]

Until there is a clear and accepted statement as to the purpose of the 1.0 release this issue remains open. For example, is the following accepted by all?

We are not looking to improve legacy code for the 1.0 release.

I'm all in favour of this (except for the 1.0 number). If enough sign up to this then the issue can be closed.

@ghickman has already signed up to this as well, but what about @doismellburning, @dbrgn and @hashbangstudio for example.

I am unclear about the purpose of the next release, and so I've reopened this issue.

[jonathanfine]

I think this is as good a place as any to discuss the version numbers.

@ghickman wrote

I will defer to @doismellburning to explain why SemVer is a great idea.

Well, http://semver.org/ writes

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

I think this is a good idea. Applying this, going from 0.9 to 1.0 means we are about to

make incompatible API changes

But I've been asking for assurances that we are NOT making such changes.

During PyConUK @doismellburning changed the version number from 0.1.1 to 0.9. I don't see how that is justified.

[dbrgn]

Semver++. But @jonathanfine is right in that we don't make reverse incompatible changes in the first release.

I think we should go for 0.9 for the first release. It symbolizes the planned release of a version 1.0 that introduces API changes (it's not actually reverse incompatible, but a "new API" that should be used instead of the new one), so a version 1.0 is justified for the new API release.

[pozorvlak]

http://semver.org also says

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.

It then makes clear (points 6-8) that the reasons for major/minor/patch increments @jonathanfine quoted above are only required for versions after 1.0.0.

My understanding of the above is that a 1.0.0 release is a declaration that the API will remain stable until release 2.0.0. This is, I think, what we want: an API that people can code against and use for teaching. A release 0.2.0 or similar would be a declaration that the API was not stable and might be changed without warning in a way that might break end-user code.

[pozorvlak]

So, here's my understanding of the roadmap:

• Release 1.0.0: first public release. API as little changed as possible from the 0.1.1 Mojang release. Works on Python 3 and 2.7.
• Releases 1.x.y: additional features and bugfixes. Experimental new APIs, marked as unstable. The old Java-flavoured API is eventually marked as deprecated once the new APIs stabilise.
• Release 2.0.0: declaration that the new APIs are now stable. Removal of the old API.

[dbrgn]

I wouldn't remove the old API in 2.0.0, just raise a DeprecationWarning. We could remove it in 3.0.0.