Choosing supported API versions in a plugin

Discussion in 'Resources' started by dktapps, Jun 20, 2018.

  1. dktapps

    dktapps Administrator Staff Member PMMP Team

    Messages:
    700
    GitHub:
    dktapps
    All plugin developers have at some point gone through the process of choosing the supported API version for a plugin. In this thread I'm going to clarify some of the criteria for API matching on the new system, and how to choose what API versions to support.

    Semver major.minor.patch API versioning
    As of PocketMine-MP 3.0.0, the API version is the same as the server version.

    Semver is roughly defined as the following:
    - Major version bump: Breaking changes - the public API has changed in such a way that it breaks thing depending on it.
    - Minor version bump: Feature additions or big changes which do not break API. This can include API methods becoming deprecated, new API features being added, but should not break plugins designed for previous minor versions.
    - Patch version bump: Usually bug fixes. These shouldn't break the API nor cause any significant alteration to the description of a version.

    PocketMine-MP uses a condition of ==.>=.>= for comparing API versions. This means that
    - The major version MUST be the same to be compatible
    - The server's minor version MUST be AT LEAST the same as the plugin's, although it can be greater.
    - The server's patch version MUST be AT LEAST the same as the plugin's, but can also be greater.

    Some examples
    - Server: 4.0.0, Plugin: 3.0.0 - NOT compatible, the major versions are different.
    - Server: 3.1.0, Plugin: 3.0.0 - IS compatible, the server has a greater minor version
    - Server: 3.0.0, Plugin: 3.1.0 - NOT compatible, the plugin requires new features
    - Server: 3.0.1, Plugin: 3.0.0 - IS compatible, the server has a greater patch version
    - Server: 3.0.0, Plugin: 3.0.1 - NOT compatible, the plugin requires newer bug fixes

    How to choose your supported API version
    You should choose the minimum version that supports the things that you need.
    For example, if the feature you want was first added in 3.1.0, you can require 3.1.0 as a minimum even if the current version is 3.2.0. This is to ensure that users get a smoother experience no matter what version of PocketMine-MP they are using. However, it may of course not make sense to require a lower version if the earlier versions are end-of-life.

    Of course, you should also test your plugin on your minimum version to make sure that everything works correctly.

    Writing requirements in your plugin manifest
    Good
    Code:
    api: [3.1.0] # this will load on any 3.x.x version newer than 3.1.0
    
    Code:
    # this will load on 3.x.x >= 3.1.0 and 4.x.x >= 4.0.0
    # the ONLY time there should be multiple versions here is if your 
    # plugin works on more than one major version without changes
    api: [3.1.0, 4.0.0]
    
    Bad
    Code:
    # DON'T do this, it is not necessary. You only need the minimum version.
    api: [3.1.0, 3.2.0, 3.3.0]
    
    Have questions or want to point out a mistake? Comment below.
     
    Angel, Palente, Darku and 7 others like this.

Share This Page

  1. This site uses cookies to help personalise content, tailor your experience and to keep you logged in if you register.
    By continuing to use this site, you are consenting to our use of cookies.