"The easy way is always mined.
 The important things are always simple.
 The simple things are always hard."
        -- Some of Murphy's Laws of Combat

This is a short set of guidelines for those contributing
ExtUtils::MakeMaker.  Its not an iron-clad set of rules, but just
things which make life easier when reading and integrating a patch.

Reporting bugs

- Often the only information we have for fixing a bug is contained in your
  report.  So...

- Please report your bugs via http://rt.cpan.org or
  https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker/issues or
  by mailing to makemaker@perl.org.
  
  RT or GitHub are preferred.

- Please report your bug immediately upon encountering it.  Do not wait
  until you have a patch to fix the bug.  Patches are good, but not at
  the expense of timely bug reports.

- Please be as verbose as possible.  Include the complete output of
  your 'make test' or even 'make test TEST_VERBOSE=1' and a copy of the 
  generated Makefile.  Err on the side of verbosity.  The more data we
  have to work with, the faster we can diagnose the problem.

- If you find an undocumented feature, or if a feature has changed/been
  added which causes a problem, report it.  Do not assume it was done
  deliberately.  Even if it was done deliberately, we still want to hear
  if it caused problems.

- If you're testing MakeMaker against a development version of Perl,
  please also check it against the latest stable version.  This makes it
  easier to figure out if its MakeMaker or Perl at fault.


Pull Request

- If you wrote a patch already, please Pull Request on GitHub.

- Pull Request against the latest development snapshot from GitHub
  repository are preferred.
  
- Pull Request against the latest CPAN version are ok, too.


Code formatting

- No literal tabs (except where necessary inside Makefile code, obviously).

- 4 character indentation.

- this_style is prefered instead of studlyCaps.

- Private subroutine names (ie. those used only in the same package
  they're declared in) should start with an underscore (_sekret_method).

- Protected subroutines (ie. ones intended to be used by other modules in
  ExtUtils::*) should be named normally (no leading underscore) but
  documented as protected (see Documentation below).

- Do not use indirect object syntax (ie. new Foo::Bar (@args))

- make variables use dollar signs like Perl scalars.  This causes problems
  when you have to mix them both in a string.  If you find yourself
  backwacking lots of dollar signs because you have one interpolated
  perl variable, like this:

    return <<EOT;
subdirs ::
	\$(NOECHO)cd $subdir && \$(MAKE) -f \$(FIRST_MAKEFILE) all \$(PASTHRU)

EOT

  or are switching quoting contexts:

    return q{
subdirs ::
	$(NOECHO)cd }.$subdir.q{ && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)

};

  consider using sprintf instead.

    return sprintf <<'EOT', $subdir;
subdirs ::
	$(NOECHO)cd %s && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)

EOT


Refactoring and Cleanup

- MakeMaker is a mess.  We like patches which clean things up.


Backwards Compatibility

- MakeMaker must be backwards compatible to 5.6.0.
  Avoid any obvious 5.8-isms. 

- MakeMaker should avoid having module dependencies.
  But if new code need depends the modules absolutely,
  it will bundle the modules.

  See Makefile.PL of ExtUtils::MakeMaker for detail. 


Cross-Platform Compatibility

- MakeMaker must work on all architectures Perl works on (see perlport.pod).
  This means all Unixen (including Cygwin and MacOS X), Windows, and VMS.

- Use the available macros rather than shell commands $(MV), $(CP),
  $(TOUCH), etc...

- MakeMaker must work on many makes.  GNU, BSD, Solaris, nmake, dmake, MMS
  and MMK to name the most common.  Keep your make code as simple as 
  possible.  

- Avoid special make variables (even $@).  

- Format targets as "target : dependency", the spacing is important.  

- Use $(NOECHO) instead of @.

- Use - to tell make to ignore the exit code of a command.  (Unfortunately,
  some make variants don't honor an $(IGNORE) macro).

- Always put a space between $(NOECHO) and the command.

- Always put a space between - (ignore) and the command.

- Always put $(NOECHO) and - together, no space between them.

        # Right
        -$(NOECHO) command
        $(NOECHO) command
        - command

- Often when you patch ExtUtils::MM_Unix, similar patches must be done
  to the other MM_* modules.  If you can, please do this extra work
  otherwise I have to.  If you can't, that's ok.  We can help.

- If possible, please test your patch on two Very Different architectures.
  Unix, Windows and VMS being Very Different.  Note: Cygwin and OS X are 
  Unixen for our purposes.

- If nothing else, at least try it on two different Unixen machines
  (ie. Linux and OS X).

- If you find yourself writing "do_this if $^O eq 'That'" (ie. checks on
  the OS type) perhaps your code belongs in one of the non-Unix MM_*
  modules (ie. MM_Win32, MM_VMS, etc...).  If one does not exist, consider
  creating one.  Its ok to have an MM_* module with only one method.

- Some shells have very small buffers.  This means command lines must
  be as small as possible.  If your command is just too long, consider
  making it an ExtUtils::Command::MM function.  If your command might
  receive many arguments (such as pod2man or pm_to_blib) consider
  using split_command() to split it into several, shorter calls.

- Most shells quote differently.  If you need to put a perl one-liner
  in the Makefile, please use oneliner() to generate it.


Tests

- Tests would be nice, but I'm not going to pretend testing MakeMaker
  is easy.  If nothing else, let us know how you tested your patch by
  hand.

- Travis CI (https://travis-ci.org) is good sources of testing
  machines of many perl versions.  Accounts are free.


Documentation

- Documentation would be nice.

- If the new feature/method is private, please document it with POD
  wrapped in "=begin/end private" tags.  That way it will be documented,
  but won't be displayed (future versions of perldoc may have options
  to display).

    =begin private

    =head3 _foo_bar

       $mm->_foo_bar

    Blah blah blah

    =end private

    =cut

    sub _foo_bar {
       ...

- If you're overriding a method, document that its an override and
  *why* its being overridden.  Don't repeat the original documentation.
