NAME notice - Breaking-Change Acknowledgement ABSTRACT Breaking-Change Acknowledgement Enforcement SYNOPSIS package Example; BEGIN { $ENV{ACK_NOTICE_EXAMPLE_UNSTABLE} = 1; } use notice unstable => { space => 'Example', until => '2020-09-01', notes => 'See https://example.com/latest/release-notes', }; 1; DESCRIPTION This package provides a mechanism for enforcing breaking-change acknowledgements. When configured under a module namespace, a fatal error (notice) will be thrown prompting the operator to acknowledge the notice (unless the notice has already been ackowledged). Notices are acknowledged by setting a predetermined environment variable. The environment variable always takes the form of ACK_NOTICE_CLASS_NOTICENAME. The fatal error (notice) is thrown whenever, the encapsulating package is "used", the notice criteria is met, and the environment variable is missing. Multiple notices can be configured and each can have a time-based expiry aftewhich the notice will never be triggered. FUNCTIONS This package implements the following functions: check check(ClassName $name, Any %args) : Maybe[Tuple[Str, Str, Str, Str, Str | ArrayRef]] The check method returns truthy or falsy based upon whether the notice criteria is met. When met, this function returns details about the trigger engaged. check example #1 # given: synopsis delete $ENV{ACK_NOTICE_EXAMPLE_UNSTABLE}; # notice: triggered (not acknowledged) notice::check('Example', ( unstable => { until => '9999-09-01', notes => 'see changelog', }, )); check example #2 # given: synopsis delete $ENV{ACK_NOTICE_EXAMPLE_UNSTABLE}; # notice: not triggered (notice expired) notice::check('Example', ( unstable => { until => '2000-09-01', notes => 'see changelog', }, )); check example #3 # given: synopsis delete $ENV{ACK_NOTICE_EXAMPLE_UNSTABLE}; # notice: triggered (not ackowledged) notice::check('Example::Agent', ( unstable => { space => 'Example', until => '9999-09-01', notes => 'see changelog', }, )); check example #4 # given: synopsis $ENV{ACK_NOTICE_EXAMPLE_UNSTABLE} = 1; # notice: triggered (refactor not ackowledged) notice::check('Example::Agent', ( refactor => { space => 'Example', until => '9999-09-01', notes => 'see refactor', }, unstable => { space => 'Example', until => '9999-09-01', notes => 'see changelog', }, )); check example #5 # given: synopsis $ENV{ACK_NOTICE_EXAMPLE_REFACTOR} = 1; $ENV{ACK_NOTICE_EXAMPLE_UNSTABLE} = 1; # notice: not triggered (unstable and refactor ackowledged) notice::check('Example::Agent', ( refactor => { space => 'Example', until => '9999-09-01', notes => 'see changelog', }, unstable => { space => 'Example', until => '9999-09-01', notes => 'see changelog', }, )); check example #6 # given: synopsis $ENV{ACK_NOTICE_EXAMPLE_UNSTABLE} = 1; # notice: triggered (wrong namespace ackowledged) notice::check('Example::Agent', ( unstable => { until => '9999-09-01', notes => 'see changelog', }, )); check example #7 # given: synopsis $ENV{ACK_NOTICE_EXAMPLE_AGENT_UNSTABLE} = 1; # notice: not triggered (notice ackowledged) notice::check('Example::Agent', ( unstable => { until => '9999-09-01', notes => 'see changelog', }, )); check example #8 # given: synopsis delete $ENV{ACK_NOTICE_EXAMPLE_UNSTABLE}; # notice: triggered (not ackowledged) notice::check('Example', ( unstable => { until => '9999-09-01', notes => [ 'see release notes for details', 'see https://example.com/latest/release-notes', ], }, )); AUTHOR Al Newkirk, awncorp@cpan.org LICENSE Copyright (C) 2011-2019, Al Newkirk, et al. This is free software; you can redistribute it and/or modify it under the terms of the The Apache License, Version 2.0, as elucidated in the "license file" . PROJECT Wiki Project Initiatives Milestones Contributing Issues