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

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".