Dist::Milla::Tutorial(3pm)

1Dist::Milla::Tutorial(3U)ser Contributed Perl DocumentatiDoinst::Milla::Tutorial(3)
2
3
4

NAME

6       Dist::Milla::Tutorial - Milla HOW TO
7

WORKFLOW

9       See also the screencast
10       <http://weblog.bulknews.net/post/46471116934/introducing-milla>
11       explaining how to setup and create a new distribution with Milla.
12
13   Setup
14       Install Milla and setup your profile.
15
16         > cpanm Dist::Milla
17         > milla setup
18
19       Setup command will ask you a simple question to make a basic profile.
20       If you already have set up "dzil" before, this is common and you can
21       skip the process.
22
23   Making a new distribution
24       Now it's time to make a new distribution.
25
26         > milla new Dist-Name
27         > cd Dist-Name
28
29       At this point, you will have a really simple "Dist-Name" directory that
30       contains your module file with as minimum boilerplate as possible.
31
32       It is recommended to track your repository under git as soon as
33       possible, even before releasing to CPAN.
34
35         # git is already initialized and files are added for you
36         > git commit -m "initial commit"
37
38       Now start writing your code, edit the docs, tests and manage CPAN
39       dependencies with cpanfile.
40
41         > $EDITOR lib/Dist/Name.pm t/dist-name.t cpanfile
42
43       You can test your code with a simple "prove -l t".
44
45       For the first time build only, you can make a test build to get some
46       boilerplate you want to keep in the git repository so that your github
47       repository looks great with README, as well as installable from git
48       using "cpanm" or testable with "Travis CI".
49
50         > milla build
51         > git add Build.PL META.json README.md && git commit -m "git stuff"
52
53   Making the first release
54       When you get confident and it's about time to ship to CPAN, use the
55       test and release command. Before doing so, make sure your git directory
56       is not dirty i.e. all changes are committed.
57
58         > git commit -a -m "Done initial version"
59
60       Milla assumes you have a git remote setup so that you can push all your
61       changes to. I recommend you to use either hub gem
62       <https://rubygems.org/gems/hub> or App::ph to create a new github
63       repository.
64
65         # Use hub rubygem
66         > hub create
67
68         # Use App::ph
69         > ph import
70
71       Now, make sure you have "Changes" file ready and have a new entry under
72       "{{$NEXT}}", which will be expanded to the next version of your module.
73
74         > $EDITOR Changes
75         > milla test
76         > milla release
77
78       And your first release is done. The release is tagged on git and all
79       the changes atomatically made are committed to git as well.
80
81       If this is your first conversion to Milla and want to make sure you're
82       not going to mess CPAN with a bad archive when something goes wrong,
83       you can run the release command with "FAKE_RELEASE" environment
84       variable. This will run all the other release process, except the
85       UploadToCPAN step.
86
87         > FAKE_RELEASE=1 milla release
88
89       Wait for PAUSE processing it and your module showing up on MetaCPAN in
90       a few minutes. Congratulations!
91
92   Making a maintainance release
93       You have new features, bugs, pull requests and get ready to make a next
94       version of your module. Great, making a new release is equally easy.
95
96       First, make sure all your code has been committed to git and there are
97       no dirty files in the working directory.
98
99       Then make sure to edit "Changes" file and contain entries for the next
100       release under "{{$NEXT}}". You don't need to commit the change to the
101       "Changes" file, yet.
102
103       Now, make a release!
104
105         > milla test
106         > milla release
107
108       The release command will automatically bump the version for you - if
109       you have 0.10, the next version will be 0.11 by default, but you will
110       be prompted to confirm that version in case you need a major bump.
111
112       This will update "Changes", "META.json" and bump $VERSION in your main
113       module. These changes made by Milla will be automatically committed,
114       tagged and pushed to the remote.
115

MIGRATING

117       This section describes how to migrate your current authoring process to
118       Milla.
119
120   Automatic migration
121       Sister project Minilla provides a wonderful conversion tool to migrate
122       your existing distribution to Milla, which happens to be compatible to
123       Milla as well.
124
125       As an author of Milla, I use Minilla's migrate command all the time to
126       get the most of conversion done.
127
128       To run Minilla migration tool, install Minilla from CPAN and run the
129       "minil migrate" command in the project root.
130
131           > cpanm Minilla
132           > minil migrate && git rm -f minil.toml
133
134       The command will output the migration process, and "git add" all the
135       changed files for you. Once the migrate command is complete, all you
136       have to do is to create "dist.ini" file, and run the build command.
137
138           > echo "[@Milla]" > dist.ini
139           > milla build
140
141       If one of the command has failed, you might need to reset to the
142       original state and run the manual migration. Read on to see how to do
143       that.
144
145   Manually migrating from other build tools
146       Module Dependencies to cpanfile
147
148       First, move the prereq declaration from "Makefile.PL" or "Build.PL" to
149       "cpanfile".
150
151       The easiest way to convert existing dependencies to cpanfile is to use
152       the command line tool "mymeta-cpanfile", which is installed with
153       Module::CPANfile. Run the configuration with "Makefile.PL" for the one
154       last time, then run the "mymeta-cpanfile" command:
155
156         > perl Makefile.PL
157         > mymeta-cpanfile --no-configure
158         requires 'DBI', '1.000';
159
160         on test => sub {
161             requires 'Test::More', '0.86';
162         }
163
164         ...
165
166       You can redirect the output to "cpanfile" if you like. It is important
167       to pass "--no-configure" option here, since otherwise modules like
168       ExtUtils::MakeMaker will be included. It is not required with Milla
169       setup, since Milla knows which configuration tool (installer) to use
170       and include them in META files upon the releases. You can leave that
171       out from the "cpanfile".
172
173       If you decide to manually construct a new cpanfile, the format is
174       mostly compatible to Module::Install's requirement DSL.
175
176         # Makefile.PL
177         test_requires 'Test::More', 0.90;
178         requires 'Plack', '1.000';
179
180       becomes:
181
182         # cpanfile
183         test_requires 'Test::More', 0.90;
184         requires 'Plack', '1.000';
185
186       which is exactly the same. If you use Module::Build or
187       ExtUtils::MakeMaker, that will be more manual process, but basically
188       the same thing. See cpanfile for the available syntax.
189
190       Remove boilerplate
191
192       Next, remove unnecessary boilerplate files.
193
194         > git rm {Makefile,Build}.PL MANIFEST MANIFEST.SKIP README .shipit
195
196       Create a new ini and edit configurations
197
198       Next, create a new "dist.ini" with the following two lines:
199
200         name = Dist-Name
201         [@Milla]
202
203       the "name = " line is optional.
204
205       If your work directory is named "Dist-Name", Milla will be able to
206       figure out that is your distribution name, so you can omit that line.
207
208       Next, Edit ".gitignore" and add the following lines:
209
210         /Dist-Name-*
211         /.build
212         !META.json
213
214       You're almost done, and your directory will look like:
215
216         cpanfile
217         dist.ini
218         lib/Dist/Name.pm
219         t/...
220
221       "git add" the newly created files and commit it.
222
223       Make a new build
224
225       Now you're ready to make the first build.
226
227         > milla build
228
229       and if it was successful, you get a build in a directory called
230       "Dist-Name-v0.1.0" under your current directory. They can be later
231       removed with "milla clean" command.
232
233       Also, new "Build.PL", "META.json" and "README.md" are added in your
234       working directory for git-friendliness. "git add" them and commit it.
235
236         > git add Build.PL META.json README.md && git commit -m "git stuff"
237
238       Now you're ready to roll a new release with Milla. Before doing so,
239       convert your "Changes" file format a little bit, and make sure you have
240       a following header in the top:
241
242         {{$NEXT}}
243                 - Change log entry for the next version
244
245       The "{{$NEXT}}" is a template variable that gets replaced with the
246       version and date string, when you make a next release. This is almost
247       the only change you're required to make in your code base.
248
249       Now, run the release command:
250
251         > milla release
252
253       to make a new release, in the same way described above for a new Milla
254       setup. You can set "FAKE_RELEASE" environment variable if this is your
255       first conversion and want to double check what happens, before
256       uploading to CPAN.
257
258       When this is not your first release, the version number gets
259       automatically bumped by Milla, but you will be prompted if that is
260       exactly the version you want, and if you want a major version up, you
261       can specify to do so.
262

AUTHOR

264       Tatsuhiko Miyagawa
265

NAME

WORKFLOW

MIGRATING

AUTHOR

SEE ALSO