=begin pod

=head1 NAME

B<Mi6::Helper> - Creates a base repository for a new Raku module managed by B<App::Mi6>

=head1 SYNOPSIS

This module installs a Raku executable named C<mi6-helper> which is
designed for the following operation:

=begin code
$ mi6-helper new=Foo::Bar
=end code

That creates a new module named C<Foo::Bar> in the current directory
(or a specified directory if the option C<dir=/path> is used).  The
new module is then ready to be enhanced and managed by app C<mi6> to
easily build build documentation, run tests, and release new versions.

=head1 DESCRIPTION

The installed program, C<mi6-helper>, enables easy creation of a
template for a new Raku module repository for management by
C<App::Mi6>.  It does that by first executing C<mi6> to create the
base module and then modifying the result to add new capabilities.
(Note the directory for module 'X::Y-Z' will be 'X-Y-Z'.  See
details in the below.)

Note when C<mi6> creates its files, it shows text in the C<README.md>
file as 'Foo::Bar - blah blah blah'. That can be changed to a brief
summary statement by creating a hidden file in the parent directory
with the same name as the new diretory. For example, new module
C<Foo::Bar> will be created in a new directory C<Foo-Bar>. You can
create hidden file C<.Foo-Bar> and put any text desired in it. The
author typically puts in text something like this:

=begin code
Provides routines to check existing module base repositories for errors.
=end code

If the hidden file does not exist, the user will be asked if he or she
wishes to continue without it. If the answer is C<yes>, then the
program will continue and the "blah blah blah" will remain. If the
answer is C<no>, the program will terminate.  (Note the program will
wait indefinitely for a response, so you should use option "force" if
you are testing or otherwise executing the program apart from a
terminal inteface.)

Run C<mi6-helper> without arguments to see its help screen showing
its options:

=begin code
Usage: mi6-helper <mode> [options...]

Modes:
  new=X - Creates a new module (named 'X') in the current directory
          by executing 'mi6', then modifying files and adding new
          files in the new repository to add the benefits produced
          by this module. NOTE: The program will abort if directory
          'X' exists.

  v[ersion] - Shows the version number and exits.

Options:

  force - Allows the program to continue without a hidden file
          and bypass the prompt/response dialog.
=end code

=head2 Post repository creation

The changes and additions in your new repository include:

1. Modifying the C<dist.ini> file for the enhancements

2. User choice of the brief descriptive text (recommended, but not required)

3. C<README.md> file source placed in a new C<docs/README.rakudoc> file
   so you can update your docs using Rakupod instead of Markdown (convert
   to updated Markdown by running C<mi6 build>).

4. Using three separate OS tests in C<.github/workflows>: shows results of each in the now auto-generated C<README.md> file

5. Publishing in the B<Zef> Raku module ecosystem (now standard with the current C<mi6>)

B<NOTE>: If one of the non-Linux OS tests fail during remote testing
on Github, you can eliminate that test by doing the following two
steps (for example, remove the C<windows> test which is the most
likely to fail):

=item Move the C<windows.yml> file out of the C<.github/workflows/> directory (the
author uses a subdir named C<dev> to hold such things).
=item Put a semicolon in the C<dist.ini> file to comment out the line naming the
C<windows.yml> file.

=head2 Modified files for the repository

In addition to those changes, the README is converted to a Rakudoc file
in a new C<./docs/> directory. Then the C<dist.ini> file is modified
to create the C<README.md> file in the base directory. Both files
are placed under C<git> control.

See L<RepoChanges|RepoChanges.md> for full details of each changed line
from the original created by C<App::Mi6>.

See published module C<Foo::Bar> for an example of a module created
by C<mi6-helper>.

=head2 Special installation requirements

The user must install and have an account with C<fez> to use this
module to create a new module repository. To do that:

=begin code
zef install fez
fez register
=end code

=head2 Define the branch C<git origin>

The author uses and recommends B<GitHub> for the C<git origin> for your
new module's repository.

A short list of steps to define such for our example 'Foo::Bar':

1. Define a new repo on GitHub named 'Foo-Bar' (note no '::' separator)

2. On your computer, use the shell terminal to run these commands (for Linux
or MacOS):

=begin code
$ cd /path/to/some-parent-dir
$ mi6-helper new=Foo::Bar
=end code

The new repository should be created with a branch name per your personal
settings for the Git default branch name (I use 'main' here). This is the
output:

=begin code
Getting description text from hidden file '.Foo-Bar'
[main (root-commit) 30a8b25] 'initial'
 12 files changed, 431 insertions(+)
 create mode 100644 .github/workflows/linux.yml
 create mode 100644 .github/workflows/macos.yml
 create mode 100644 .github/workflows/windows.yml
 create mode 100644 .gitignore
 create mode 100644 Changes
 create mode 100644 LICENSE
 create mode 100644 META6.json
 create mode 100644 README.md
 create mode 100644 dist.ini
 create mode 100644 docs/README.rakudoc
 create mode 100644 lib/Foo/Bar.rakumod
 create mode 100644 t/0-load-test.rakutest
Using directory '/path/to/some-parent-dir'
  as the working directory.
Exit after 'new' mode run. See new module repo 'Foo-Bar'
in parent dir '/path/to/some-parent-dir'.
=end code

At this point, execute the following commands to define the origin and
push the new branch to the repo awaiting it on GitHub:

=begin code
# GitHub shows this choice: ...or push an existing repository from the command line...
# We follow those instructions with our fresh 'Foo::Bar' repo:
$ git remote add origin git@github.com:user/Foo-Bar.git
$ git branch -M main
$ git push -u origin main
=end code

=head2 Windows WARNING

This package may fail the full test suite on GitHub. 
This user does not have a Windows host, so no help can be had from
him. Check with the Windows experts on L<Chocolatey|https://www.chocolatey.org>
for help.

=head2 See also

A new, in-work L<App::DistroLint|https://github.com/tbrowder/App-DistroLint>
by the author.

=head1 AUTHOR

Tom Browder <tbrowder@acm.org>

=head1 CREDITS

The very useful Raku modules used herein:

=item L<C<App::Mi6>|https://github.com/skaji/mi6>              by B<zef:skaji>
=item L<C<File::Directory::Tree>|https://github.com/labster/p6-file-directory-tree> by B<github:labster>
=item L<C<File::Temp>|https://github.com/raku-community-modules/File-Temp>            by B<zef:rbt>
=item L<C<Proc::Easier>|https://github.com/sdondley/Proc-Easier>          by B<zef:sdondley>
=item L<C<File::Find>|https://github.com/raku-community-modules/File-Find>            by B<zef:raku-community-modules>
=item L<C<MacOS::NativeLib>|https://github.com/lizmat/MacOS-NativeLib>      by B<zef:lizmat>

=head1 COPYRIGHT AND LICENSE

&#x00A9; 2020-2026 Tom Browder

This library is free software; you may redistribute it or modify it under the Artistic License 2.0.

=end pod
