package Rinci::Upgrading; # just to make PodWeaver happy # AUTHORITY # DATE our $DIST = 'Rinci'; # DIST # VERSION 1; # ABSTRACT: Upgrading from previous version of specification __END__ =pod =encoding UTF-8 =head1 NAME Rinci::Upgrading - Upgrading from previous version of specification =head1 VERSION This document describes version 1.1.104 of Rinci::Upgrading (from Perl distribution Rinci), released on 2023-09-30. =head1 DESCRIPTION This document gives guide on how to convert your metadata from older version. Examples are written in Perl, but are not limited to this language. =head1 UPGRADING FROM SUB::SPEC 1.0 TO RINCI 1.1 =head2 Upgrading function metadata In Perl, you can use L (which in turn is used by L) to automatically convert Sub::Spec 1.0 metadata to 1.1, so you can skip this document if you want. Terminology change: B<(sub) spec> is now called metadata: the reason is because there are now metadata for functions as well as other code entities like variables, packages, etc. B is now called B: the reason is to avoid confusion with L's clause. The C (spec version) property is required, add v => 1.1 to your function metadata. Each argument in the C property is now a hash, instead of a schema. Move the schema to the C key of the hash. To specify required argument, add C set to 1 to hash key. Move C Sah clause to C hash key. Move C Sah clause to C hash key. Move C Sah clause to C hash key. Example, change this: args => { # a required argument arg1 => ['int*', { summary => 'Blah ...', min => 1, max => 100, arg_pos => 0, }], # an optional argument arg2 => ['bool', { summary => 'Blah ...', default => 0, }], } Into this: args => { arg1 => { summary => 'Blah ...', schema => ['int*', {min=>1, max=>100}], req => 1, pos => 0, }, arg2 => { summary => 'Blah ...', schema => [bool => {default=>0}], }, } It is now possible to give summary and description to the schema as well as to the argument. Accordingly, the C property is also now a hash, instead of schema. Move the schema into the C hash key. =head2 Sub::Spec::HTTP For the most part, you only need to upgrade client and server library. Client library is now L and L. Server library is now C. Specification is now L and L. Terminology changes. B now becomes B. Some key names changed (shortened). Special headers are now prefixed with B instead of B. Log levels are now numeric only (1-6) instead of numeric/string. =head1 HOMEPAGE Please visit the project's homepage at L. =head1 SOURCE Source repository is at L. =head1 AUTHOR perlancar =head1 CONTRIBUTING To contribute, you can send patches by email/via RT, or send pull requests on GitHub. Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via: % prove -l If you want to build the distribution (e.g. to try to install it locally on your system), you can install L, L, L, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me. =head1 COPYRIGHT AND LICENSE This software is copyright (c) 2023, 2022, 2021, 2020, 2019, 2018, 2017, 2016, 2015, 2014, 2013, 2012 by perlancar . This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. =head1 BUGS Please report any bugs or feature requests on the bugtracker website L When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. =cut