=encoding utf8 =for stopwords gitignore cpanfile mymeta PL UploadToCPAN MetaCPAN =head1 NAME =begin original Minilla::Tutorial - Tutorial document for Minilla =end original Minilla::Tutorial - Minilla チュートリアルドキュメント =head1 The Minilla workflow (Minillaのワークフロー) =head2 Installing (インストール) =begin original > cpanm Minilla You can install L from CPAN. =end original > cpanm Minilla CPANからインストールできます。 =begin original Unlike L, you don't need to any setup. L aggregates user name and e-mail address from your C<~/.gitconfig> (You already set, isn't it?) =end original L と違って、なんのセットアップも必要ありません。L はユーザー名と電子メールアドレスを C<~/.gitconfig>から 集めます(既に設定しているでしょ?)。 =head2 Making new distribution (新しいディストリビューションを作る) =begin original Now it's time to make a new distribution. =end original さぁ、新しいディストリビューションを作りましょう。 > minil new Dist-Name > cd Dist-Name/ =begin original At this point, you will have a really simple Dist-Name directory that contains your module file with as minimum boilerplate as possible. =end original この時点では、本当に単純な、可能な限り最小限のボイラープレートとモジュールファイルを含んだディストリビューションの名前のディレクトリができます。 =begin original L done C and C. You need to commit it ASAP. =end original L は C と Cを行います。可能な限り早くに commit しなければいけません。 > git commit -m 'initial import' =begin original Now start writing your code, edit the docs, tests and manage CPAN dependencies with L. =end original コードを書き、ドキュメントを編集し、テストをし、CPANの依存関係を L で管理します。 > $EDITOR lib/Dist/Name.pm t/dist-name.t cpanfile =head2 Making the first release (最初のリリースをする) =begin original When you get confident and it's about time to ship to CPAN, use the test and release command. Before doing so, make sure your git directory is not dirty i.e. all changes are committed. =end original 自信が持てたら、CPAN に ship する時です。test と relaese コマンドを使います。それをする前に、git ディレクトリが汚れていないことを確認してください。すべての変更が commit されます。 > git commit -a -m "Done initial version" =begin original Minilla assumes you have a git remote setup so that you can push all your changes to. I recommend you to use either hub gem or L to create a new github repository. =end original Minilla は、すべての変更を push する git remote が設定されていることを想定しています。新しいリポジトリを作るために、hub gem か Lを使うことをおすすめします。 # Use hub rubygem > hub create # Use App::ph > ph import =begin original Now, make sure you have Changes file ready and have a new entry under C<{{$NEXT}}>, which will be expanded to the next version of your module. =end original Changes ファイルがあり、C<{{$NEXT}}>の下に新しいエントリがあることを確認します。 C<{{$NEXT}}>は、モジュールの次のバージョンに展開されます。 > $EDITOR Changes > minil test =begin original Before you proceed to release step, please ensure the C<~/.pause> file is configured correctly because Minilla uses L to upload your distribution to CPAN. You can specify the location of PAUSE configuration file on I if you want to. See L for further information. =end original リリースステップに進む前に、C<~/.pause> ファイルが正確に設定されていることを確かめてください。Minilla は L をディストリビューションをCPANにアップロードするのに使うからです。PAUSE の設定ファイルの場所を、もし望むなら I に指定できます。 > minil release =begin original And your first release is done. The release is tagged on git and all the changes automatically made are committed to git as well. =end original 最初のリリースが終わりました。リリースは git にタグ付けされ、すべての変更は自動的に git にコミットされます。 =begin original If this is your first conversion to Minilla and want to make sure you're not going to mess CPAN with a bad archive when something goes wrong, you can run the release command with FAKE_RELEASE environment variable. This will run all the other release process, except the UploadToCPAN step. =end original もし、これがMinillaとの最初のやりとりで、何かが間違っていいて、正しくないアーカイブで CPAN を汚さないことを確認したければ、FAKE_RELEASE 環境変数をつけて release コマンドを実行してください。これは、UploadToCPAN ステップ以外、すべての他のリリースプロセスを実行します。 > FAKE_RELEASE=1 minil release =begin original Wait for PAUSE processing it and your module showing up on MetaCPAN in a few minutes. Congratulations! =end original PAUSE の処理を待ち、モジュールが MetaCPAN に数分で現れます。おめでとう! =head2 Making a maintenance release (メンテナンスリリースを行う) =begin original You have new features, bugs, pull requests and get ready to make a next version of your module. Great, making a new release is equally easy. =end original 新しい機能や、バグ、プルリクエストなどがあり、モジュールの次のバージョンを出す準備ができました。新しいリリースをするのも、同様に簡単です。 =begin original First, make sure all your code has been committed to git and there's no dirty files in the working directory. =end original まず、すべてのコードが git にコミットされており、ダーティファイルがワーキングディレクトリにないことを確認します。 =begin original Then make sure to edit Changes file and contain entries for the next release under C<{{$NEXT}}>. You don't need to commit the change to the I file, yet. =end original それから、Changes ファイルを確実に編集し、C<{{$NEXT}}> の下に、次のリリースのためのエントリを書きます。まだ、I ファイルへの変更をコミットする必要はありません。 =begin original Now, make a release! =end original さぁ、リリースしましょう! > minil test > minil release =begin original The release command will automatically bump the version for you - if you have 0.10, the next version will be 0.11 by default, but you will be prompted to confirm that version in case you need a major bump. =end original リリースコマンドは、自動的にバージョンを増加させます。 - 0.10であれば、次のバージョンは デフォルトでは 0.11 です。ですが、メジャーバージョンアップをするときために、確認が促されます。 =begin original You can annotate any lines for which you would like the automatic version bump to be skipped by appending, `# No BumpVersion`. =end original あなたは、 `、＃ No BumpVersion` を付加することによって、自動バージョンバンプをスキップし、ご希望の注釈をつけることができます。 You can annotate any lines for which you would like the automatic version bump to be skipped by appending, `# No BumpVersion`. =begin original This will update C, C and bump C<$VERSION> in your main module. These changes made by Minilla will be automatically committed, tagged and pushed to the remote. =end original これにより、C、C と メインモジュールの C<$VERSION> が増加します。 Minilla が行うこれらの変更は自動的にコミットされ、タグ付けされ、リモートにプッシュされます。 =head1 MIGRATING (移行) =begin original This section describes how to migrate your current authoring process to Minilla. =end original このセクションでは、現在のオーサリングプロセスをMinillaに移行する方法について書いています。 =head2 Migrate by C (C による移行) =begin original You just type C. =end original C とタイプするだけです。 =begin original It can migrate your distribution automatically. If you can't do it, please report to L. =end original このコマンドでディストリビューションは自動的に移行することができます。これが動かなければ、 L に報告してください。 =head2 Manually migrating from other build tools (ビルドツールによる手動での移行) =head3 Module Dependencies to cpanfile (モジュールの依存性を cpanfile に) =begin original First, move the prereq declaration from Makefile.PL or Build.PL to cpanfile. =end original 最初に、Makefile.PL、Build.PLの prereq 宣言を cpanfile に移動します。 =begin original The easiest way to convert existing dependencies to cpanfile is to use the command line tool mymeta-cpanfile, which is installed with L. Run the configuration with Makefile.PL for the one last time, then run the mymeta-cpanfile command: =end original 既存の依存性を cpanfile に変換するもっとも簡単な方法は、 コマンドラインツールの mymeta-cpanfile をつかうことです。このコマンドは L でインストールされます。最後に一度、Makefile.PLで設定を走らせた後、mymeta-cpanfile コマンドを動かします: > perl Makefile.PL > mymeta-cpanfile --no-configure requires 'DBI', '1.000'; on test => sub { requires 'Test::More', '0.86'; } ... =begin original You can redirect the output to cpanfile if you like. It is important to pass --no-configure option here, since otherwise modules like ExtUtils::MakeMaker will be included. It is not required with Minilla setup, since Minilla knows which configuration tool (installer) to use and include them in META files upon the releases. You can leave that out from the cpanfile. =end original 望むなら、出力を cpanfile にリダイレクトできます。--no-configure オプションをここで渡すのが重要です。そうしないと、ExUtils::MakeMaker のようなモジュールが含まれてしまします。これは Minilla のセットアップでは必要ありません。Minilla はどの設定ツール(インストーラ)を使うか知っており、リリース時に META ファイルにそれらを含めます。ですので、cpanfile からそれらを無視することができます。 =begin original If you decide to manually construct new cpanfile, the format is mostly compatible to Module::Install's requirement DSL. =end original 新しい cpanfile を手で作ると決めたなら、フォーマットは Module::Install の要求の DSL とほとんど互換性があります。 # Makefile.PL test_requires 'Test::More', 0.90; requires 'Plack', '1.000'; =begin original becomes: =end original 次のようになります: # cpanfile test_requires 'Test::More', 0.90; requires 'Plack', '1.000'; =begin original which is exactly the same. If you use L or L, that will be more manual process, but basically the same thing. See L for the available syntax. =end original まったく同じです。L か L を使うなら、より手で行うプロセスがありますが、基本的には同じです。利用可能なシンタックスについては L をみてください。 =head3 Remove boilerplate (ボイラープレートの削除) =begin original Next, remove unnecessary boilerplate files. =end original 次に、不要なボイラープレートファイルを削除します。 > git rm {Makefile,Build}.PL MANIFEST MANIFEST.SKIP README .shipit =head3 Edit configurations (設定を編集する) =begin original Edit .gitignore and add the following lines: =end original .gitignore を編集し、次の行を加えます: /Dist-Name-* /.build !META.json =begin original You're almost done, and your directory will look like: =end original ほとんど終わりです。ディレクトリは次のようになります: cpanfile lib/Dist/Name.pm t/... =begin original C the newly created files and commit it. =end original 新しく作られたファイルを C して、コミットします。 =head3 Make a new build (新しいビルドを作成) =begin original Now you're ready to make the first build. =end original さぁ、最初のビルドをする準備ができました。 > minil build =begin original and if it was successful, you get a build in a directory called C under your current directory. They can be later removed with C command. =end original そして、成功したなら、カレントディレクトリの下に、C のような名前のディレクトリができます。後で、C コマンドで削除できます。 =begin original Also, new C, C and C are added in your working directory for git-friendliness. C them and commit it. =end original また、ワーキングディレクトリに、git用の親切のために、新しく C、C、 C が追加されます。C して、コミットしてください。 また、ワーキングディレクトリに、git用の親切のために、新しく C、C、 > git add Build.PL META.json README.md && git commit -m "git stuff" =begin original Now you're ready to roll a new release with Minilla. Before doing so, convert your C file format a little bit, and make sure you have a following header in the top: =end original Minillaで新しくリリースをする準備ができました。その前に、C ファイルフォーマットを 少し変更し、トップに次のヘッダがあることを確認します。 {{$NEXT}} - Change log entry for the next version =begin original The C<{{$NEXT}}> is a template variable that gets replaced with the version and date string, when you make a next release. This is almost the I change you're required to make in your code base. =end original C<{{$NEXT}}> は、次のリリースを行うときに、バージョンとデータ文字列で 置き換えられるテンプレートの変数です。これは、元のコードベースから必要な ほとんどI<唯一>の変更です。 =begin original Now, run the release command: =end original さぁ、リリースコマンドを実行しましょう: > minil release =begin original to make a new release, in the same way described above for a new Minilla setup. You can set C environment variable if this is your first conversion and want to double check what happens, before uploading to CPAN. =end original 新しいMinillaのセットアップのために、上述と同じ方法で、新しいリリースを作ります。 最初の変換で、CPANにアップする前に、何が起きるかダブルチェックしたければ、 C 環境変数をセットできます。 =begin original When this is not your first release, the version number gets automatically bumped by Minilla, but you will be prompted if that is exactly the version you want, and if you want a major version up, you can specify to do so. =end original 最初のリリースでなければ、バージョン番号は自動的にMinillaによって、増加されます。 ですが、実際に望んでいるバージョンかどうか確認を促されます。 もし、メジャーバージョンアップをしたければ、そのように指定できます。 =head1 AUTHOR Tokuhiro Matsuno Tatsuhiko Miyagawa (Most of documents are taken from L!) =head1 SEE ALSO L, L =cut