libvirt.org/go/libvirtxml@v1.10003.0/VERSIONING.rst (about)

     1  ================================================
     2  Versioning information for libvirt-go-xml-module
     3  ================================================
     4  
     5  Release schedule
     6  ================
     7  
     8  The XML manipulation library follows the same `release schedule`_ as
     9  the main C library, with new releases of both usually being tagged at
    10  the same time.
    11  
    12  .. _release schedule: https://libvirt.org/downloads.html#schedule
    13  
    14  
    15  Versioning scheme
    16  =================
    17  
    18  Despite the release schedule being the same, the XML manipulation
    19  library do **not** follow the same `versioning scheme`_ as the main C
    20  library.
    21  
    22  The XML manipulation library has adopted `semantic versioning`_,
    23  which is both expected in the Go ecosystem and extremly important in
    24  order to work correctly within the Go module system.
    25  
    26  When it's time to tag a new release, the logic described below is
    27  followed: in this example, we will assume that the most recent
    28  release of the XML manipulation library is ``v0.7005.0`` (made along
    29  libvirt 7.5.0) and that libvirt 7.6.0 has just been tagged.
    30  
    31  * if libvirt 7.6.0 introduces changes to the XML schema
    32  
    33    * make sure the XML manipulation library is aware of them and tag
    34      the result as ``v0.7006.0``
    35  
    36  * if libvirt 7.6.0 doesn't introduce changes to the XML schema
    37  
    38    * if there have been other tweaks and changes to the XML
    39      manipulation library since ``v0.7005.0``
    40  
    41      * tag the current code as ``v0.7005.1``
    42  
    43    * if the XML manipulation library is completely unchanged from
    44      ``v0.7005.0``
    45  
    46      * do nothing
    47  
    48  This versioning scheme has the following desirable properties:
    49  
    50  * it complies with the semantic versioning specification;
    51  
    52  * it contains an encoded version of the libvirt XML schema it
    53    implements, making it easy to tell at a glance whether or not the
    54    libvirt functionality you're interested in will be available to
    55    your Go application;
    56  
    57  * it removes the need for users to update their import paths once per
    58    year even though the XML manipulation library has retained complete
    59    backwards compatibility;
    60  
    61  * it avoids the situation where a new version of the XML manipulation
    62    library is tagged even though it contains no actual changes, as
    63    well as the opposite scenario where fixes made to the XML
    64    manipulation library cannot make it into a release until the C
    65    library introduces a new XML element or attribute.
    66  
    67  .. _versioning scheme: https://libvirt.org/downloads.html#numbering
    68  .. _semantic versioning: https://semver.org/