view release on metacpan or  search on metacpan

lib/Alien/Build/Manual/Contributing.pod  view on Meta::CPAN

# PODNAME: Alien::Build::Manual::Contributing
# ABSTRACT: Over-detailed contributing guide
# VERSION

__END__

=pod

=encoding UTF-8

=head1 NAME

Alien::Build::Manual::Contributing - Over-detailed contributing guide

=head1 VERSION

version 2.84

=head1 SYNOPSIS

 perldoc Alien::Build::Manual::Contributing

=head1 DESCRIPTION

Thank you for considering to contribute to my open source project!  If
you have a small patch please consider just submitting it.  Doing so
through the project GitHub is probably the best way:

L<https://github.com/plicease/Alien-Build/issues>

If you have a more invasive enhancement or bugfix to contribute, please
take the time to review these guidelines.  In general it is good idea to
work closely with the L<Alien::Build> developers, and the best way to
contact them is on the C<#native> IRC channel on irc.perl.org.

=head2 History

Joel Berger wrote the original L<Alien::Base>.  This distribution
included the runtime code L<Alien::Base> and an installer class
L<Alien::Base::ModuleBuild>.  The significant thing about L<Alien::Base>
was that it provided tools to make it relatively easy for people to roll
their own L<Alien> distributions.  Over time, the PerlAlien (github
organization) or "Alien::Base team" has taken over development of
L<Alien::Base> with myself (Graham Ollis) being responsible for
integration and releases.  Joel Berger is still involved in the project.

Since the original development of L<Alien::Base>, L<Module::Build>, on
which L<Alien::Base::ModuleBuild> is based, has been removed from the
core of Perl.  It seemed worthwhile to write a replacement installer
that works with L<ExtUtils::MakeMaker> which IS still bundled with the
Perl core.  Because this is a significant undertaking it is my intention
to integrate the many lessons learned by Joel Berger, myself and the
"Alien::Base team" as possible.  If the interface seems good then it is
because I've stolen the ideas from some pretty good places.

=head2 Philosophy

=head3 Alien runtime should be as config-only as possible.

Ideally the code for an L<Alien::Base> based L<Alien> should simply
inherit from L<Alien::Base>, like so:

 package Alien::libfoo;
 
 use parent qw( Alien::Base );
 
 1;

The detection logic should be done by the installer code (L<alienfile>
and L<Alien::Build>) and saved into runtime properties (see
L<Alien::Build/runtime_prop>).  And as much as
possible the runtime should be implemented in the base class (L<Alien::Base>).
Where reasonable, the base class should be expanded to meet the needs
of this arrangement.

=head3 when downloading a package grab the latest version

If the maintainer of an L<Alien> disappears for a while, and if the
version downloaded during a "share" install is hardcoded in the
L<alienfile>, it can be problematic for end-users.

There are exceptions, of course, in particular when a package provides
a very unstable interface from version to version it makes sense
to hard code the version and for the Alien developer and Alien consumer
developer to coordinate closely.

=head3 when installing a package the operating system as a whole should not be affected

The convenience of using an L<Alien> is that a user of a CPAN module
that consumes an L<Alien> doesn't need to know the exact incantation
to install the libraries on which it depends (or indeed it may not be
easily installed through the package manager anyway).

As a corollary, a user of a CPAN module that consumes an L<Alien>
module shouldn't expect operating system level packages to be
installed, or for these packages to be installed in common system
level directories, like C</usr/local> or C</opt>.  Instead a "share"
directory associated with the Perl install and L<Alien> module
should be used.

Plugins that require user opt-in could be written to prompt a user
to automatically install operating system packages, but this should
never be done by default or without consent by the user.

=head3 avoid dependencies

One of the challenges with L<Alien> development is that you are by the