Minilla-v0.6.4 > Minilla::Tutorial
Minilla-v0.6.4

名前

Minilla::Tutorial - Tutorial document for Minilla

Minilla::Tutorial - Minilla チュートリアルドキュメント

Minillaのワークフロー

インストール

    % cpanm Minilla

You can install Minilla from CPAN (I don't released yet@20130325)

CPANからインストールできます。 (020130325までリリースしません)

Unlike dzil, you don't need to any setup. Minilla aggregates user name and e-mail address from your ~/.gitconfig (You already set, isn't it?)

dzil と違って、なんのセットアップも必要ありません。Minilla はユーザー名と電子メールアドレスを ~/.gitconfigから 集めます(既に設定しているでしょ?)。

新しいディストリビューションを作る

Now it's time to make a new distribution.

さぁ、新しいディストリビューションを作りましょう。

    % minil new Dist-Name
    % cd Dist-Name/

At this point, you will have a really simple Dist-Name directory that contains your module file with as minimum boilerplate as possible.

この時点では、本当に単純な、可能な限り最小限のボイラーブレーととモジュールファイルを含んだディストリビューションの名前のディレクトリができます。

minil done git init and git add .. You need to commit it ASAP.

minilgit initgit add .を行います。可能な限り早くに commit しなければいけません。

    % git commit -m 'initial import'

Now start writing your code, edit the docs, tests and manage CPAN dependencies with cpanfile.

コードを書き、ドキュメントを編集し、テストをし、CPANの依存関係を cpanfile で管理します。

    % $EDITOR lib/Dist/Name.pm t/dist-name.t cpanfile

最初のリリースをする

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.

自信が持てたら、CPAN に ship する時です。test と relaese コマンドを使います。それをする前に、git ディレクトリが汚れていないことを確認してください。すべての変更が commit されます。

    % git commit -a -m "Done initial version"

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 App::ph to create a new github repository.

Minilla は、すべての変更を push する git remote が設定されていることを想定しています。新しいリポジトリを作るために、hub gem か App::phを使うことをおすすめします。

    # Use hub rubygem
    > hub create
    
    # Use App::ph
    > ph import

Now, make sure you have Changes file ready and have a new entry under {{$NEXT}}, which will be expanded to the next version of your module.

Changes ファイルがあり、{{$NEXT}}の下に新しいエントリがあることを確認します。 {{$NEXT}}は、モジュールの次のバージョンに展開されます。

    % $EDITOR Changes
    % minil test
    % minil release

And your first release is done. The release is tagged on git and all the changes automatically made are committed to git as well.

最初のリリースが終わりました。リリースは git にタグ付けされ、すべての変更は自動的に git にコミットされます。

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.

もし、これがMinillaとの最初のやりとりで、何かが間違っていいて、正しくないアーカイブで CPAN を汚さないことを確認したければ、FAKE_RELEASE 環境変数をつけて release コマンドを実行してください。これは、UploadToCPAN ステップ以外、すべての他のリリースプロセスを実行します。

    > FAKE_RELEASE=1 minil release

Wait for PAUSE processing it and your module showing up on MetaCPAN in a few minutes. Congratulations!

PAUSE の処理を待ち、モジュールが MetaCPAN に数分で現れます。おめでとう!

メンテナンスリリースを行う

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.

新しい機能や、バグ、プルリクエストなどがあり、モジュールの次のバージョンを出す準備ができました。新しいリリースをするのも、同様に簡単です。

First, make sure all your code has been committed to git and there's no dirty files in the working directory.

まず、すべてのコードが git にコミットされており、ダーティファイルがワーキングディレクトリにないことを確認します。

Then make sure to edit Changes file and contain entries for the next release under {{$NEXT}}. You don't need to commit the change to the Changes file, yet.

それから、Changes ファイルを確実に編集し、{{$NEXT}} の下に、次のリリースのためのエントリを書きます。まだ、Changes ファイルへの変更をコミットする必要はありません。

Now, make a release!

さぁ、リリースしましょう!

    % minil test
    % minil release

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.

リリースコマンドは、自動的にバージョンを増加させます。 - 0.10であれば、次のバージョンは デフォルトでは 0.11 です。ですが、メジャーバージョンアップをするときために、確認が促されます。

This will update Changes, META.json and bump $VERSION in your main module. These changes made by Minilla will be automatically committed, tagged and pushed to the remote.

これにより、ChangesMETA.json と メインモージュールの $VERSION が増加します。 Minilla が行うこれらの変更は自動的にコミットされ、タグ付けされ、リモートにプッシュされます。

移行

This section describes how to migrate your current authoring process to Minilla.

このセクションでは、現在のオーサリングプロセスをMinillaに移行する方法について書いています。

Migrate by minil migrate

(minil migrate による移行)

You just type minil migrate.

minil migrate とタイプするだけです。

It can migrate your distribution automatically. If you can't do it, please report to Github issues.

このコマンドでディストリビューションは自動的に移行することができます。これが動かなければ、 Github issues に報告してください。

ビルドツールによる手動での移行

モジュールの依存性を cpanfile に

First, move the prereq declaration from Makefile.PL or Build.PL to cpanfile.

最初に、Makefile.PL、Build.PLの prereq 宣言を cpanfile に移動します。

The easiest way to convert existing dependencies to cpanfile is to use the command line tool mymeta-cpanfile, which is installed with Module::CPANfile. Run the configuration with Makefile.PL for the one last time, then run the mymeta-cpanfile command:

既存の依存性を cpanfile に変換するもっとも簡単な方法は、 コマンドラインツールの mymeta-cpanfile をつかうことです。このコマンドは Module::CPANfile でインストールされます。最後に一度、Makefile.PLで設定を走らせた後、mymeta-cpanfile コマンドを動かします:

    > perl Makefile.PL
    > mymeta-cpanfile --no-configure
    requires 'DBI', '1.000';
    
    on test => sub {
        requires 'Test::More', '0.86';
    }
        
    ...

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.

望むなら、出力を cpanfile にリダイレクトできます。--no-configure オプションをここで渡すのが重要です。そうしないと、ExUtils::MakeMaker のようなモジュールが含まれてしまします。これは Minilla のセットアップでは必要ありません。Minilla はどの設定ツール(インストーラ)を使うか知っており、リリース時に META ファイルにそれらを含めます。ですので、cpanfile からそれらを無視することができます。

If you decide to manually construct new cpanfile, the format is mostly compatible to Module::Install's requirement DSL.

新しい cpanfile を手で作ると決めたなら、フォーマットは Module::Install の要求の DSL とほとんど互換性があります。

    # Makefile.PL
    test_requires 'Test::More', 0.90;
    requires 'Plack', '1.000';

becomes:

次のようになります:

    # cpanfile
    test_requires 'Test::More', 0.90;
    requires 'Plack', '1.000';

which is exactly the same. If you use Module::Build or ExtUtils::MakeMaker, that will be more manual process, but basically the same thing. See cpanfile for the available syntax.

まったく同じです。Module::BuildExtUtils::MakeMaker を使うなら、より手で行うプロセスがありますが、基本的には同じです。利用可能なシンタックスについては cpanfile をみてください。

ボイラープレートの削除

Next, remove unnecessary boilerplate files.

次に、不要なボイラープレートファイルを削除します。

    > git rm {Makefile,Build}.PL MANIFEST MANIFEST.SKIP README .shipit

設定を編集する

Edit .gitignore and add the following lines:

.gitignore を編集し、次の行を加えます:

    /Dist-Name-*
    /.build
    !META.json

You're almost done, and your directory will look like:

ほとんど終わりです。ディレクトリは次のようになります:

    cpanfile
    lib/Dist/Name.pm
    t/...

git add the newly created files and commit it.

新しく作られたファイルを git add して、コミットします。

新しいビルドを作成

Now you're ready to make the first build.

さぁ、最初のビルドをする準備ができました。

    > minil build

and if it was successful, you get a build in a directory called Dist-Name-v0.1.0 under your current directory. They can be later removed with minil clean command.

そして、成功したなら、カレントディレクトリの下に、Dist-Name-v0.1.0 のような名前のディレクトリができます。後で、minl clean コマンドで削除できます。

Also, new Build.PL, META.json and README.md are added in your working directory for git-friendliness. git add them and commit it.

また、ワーキングディレクトリに、git用の親切のために、新しく Build.PLMETA.jsonREADME.md が追加されます。git add して、コミットしてください。 また、ワーキングディレクトリに、git用の親切のために、新しく Build.PLMETA.json

   > git add Build.PL META.json README.md && git commit -m "git stuff"
    

Now you're ready to roll a new release with Minilla. Before doing so, convert your Changes file format a little bit, and make sure you have a following header in the top:

Minillaで新しくリリースをする準備ができました。その前に、Changes ファイルフォーマットを 少し変更し、トップに次のヘッダがあることを確認します。

  {{$NEXT}}

    - Change log entry for the next version

The {{$NEXT}} is a template variable that gets replaced with the version and date string, when you make a next release. This is almost the only change you're required to make in your code base.

{{$NEXT}} は、次のリリースを行うときに、バージョンとデータ文字列で 置き換えられるテンプレートの変数です。これは、元のコードベースから必要な ほとんど唯一の変更です。

Now, run the release command:

さぁ、リリースコマンドを実行しましょう:

    > minil release

to make a new release, in the same way described above for a new Minilla setup. You can set FAKE_RELEASE environment variable if this is your first conversion and want to double check what happens, before uploading to CPAN.

新しいMinillaのセットアップのために、上述と同じ方法で、新しいリリースを作ります。 最初の変換で、CPANにアップする前に、何が起きるかダブルチェックしたければ、 FAKE_RELEASE 環境変数をセットできます。

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.

最初のリリースでなければ、バージョン番号は自動的にMinillaによって、増加されます。 ですが、実際に望んでいるバージョンかどうか確認を促されます。 もし、メジャーバージョンアップをしたければ、そのように指定できます。

作者

Tokuhiro Matsuno

Tatsuhiko Miyagawa (Most of documents are taken from Dist::Milla::Tutorial!)

SEE ALSO

Minilla, Dist::Milla::Tutorial