package Setup; # to make podweaver happy

our $VERSION = '1.0.4'; # VERSION

1;
# ABSTRACT: Specification for setup module


__END__
=pod

=head1 NAME

Setup - Specification for setup module

=head1 VERSION

version 1.0.4

=head1 SPECIFICATION VERSION

1.0

=head1 SPECIFICATION

This is a specification for setup modules. Setup modules are normal Perl modules
that live under the C<Setup::> namespace and contain setup functions. Setup
functions are normal Perl subroutines, typically named with C<setup_> prefix
(like C<setup_file>, C<setup_unix_user>, etc.) They are typically used for,
well, setting up stuffs, like software installation, system setup, or
configuration management.

Setup functions MUST have metadata, as specified in L<Rinci> specification.

Setup function MUST use L<Log::Any> for logging.

Setup functions MUST support transactions, as described in
L<Rinci::Transaction>.

Since setup functions might be used in unsetup (uninstallation) of software
months or even years after setup (installation), their interface should be
stable. During setup, undo actions are recorded in transaction database and
might be used years later.

Setup function should log something like this in the C<check_state> phase when
in dry-run mode, to give messages to user:

 my $tx_action = $args{-tx_action};
 my $dry_run   = $args{-dry_run};
 if ($tx_action eq 'check_state') {
     ...
     $log->infof("(DRY) Trashing %s ...", $path);
     return [200, "Path $path should be trashed", undef, {undo_actions=>\@u}];
 }

Setup function should log something like this when about to perform action in
C<fix_state> phase:

 # example 1: trashing a file
 $log->infof("Trashing %s ...", $path);
 $trash->trash($path);

 # example 2: creating a user
 $log->infof("Adding user %s ...", $user);
 $res = add_user(user=>$user, ...);

=head1 AUTHOR

Steven Haryanto <stevenharyanto@gmail.com>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Steven Haryanto.

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 CHANGES

=head2 Version 1.0.4 (2012-09-04)

=over 4

=item *

Specify how function should log dry-run message and message before

=item *

performing action in 'fix_state' phase.

=back

=head2 Version 1.0.3 (2012-08-21)

=over 4

=item *

Follow Rinci 1.1.24. Simplify description (idempotency is implied by

=item *

transaction protocol). Remove requirement of using

=item *

Perinci::Sub::Gen::Undoable since it is now deprecated.

=back

=head2 Version 1.0.2 (2012-08-14)

=over 4

=item *

No functional changes. Follow Rinci 1.1.23. Simplify description.

=back

=head2 Version 1.0.1 (2012-05-31)

=over 4

=item *

Simplify description, as most functionality is now already described in

=item *

more detail by Rinci 1.1.17+ and Riap 1.1.13+'s transaction/undo

=item *

protocol.

=back

=head2 Version 1.0.0 (2012-03-28)

=over 4

=item *

First release, split from Setup-File.

=back

=cut

