Commit | Line | Data |
054577ba |
1 | # NAME |
2 | |
3 | Distar - Additions to ExtUtils::MakeMaker for dist authors |
4 | |
5 | # SYNOPSIS |
6 | |
7 | `Makefile.PL`: |
8 | |
9 | use ExtUtils::MakeMaker; |
10 | (do './maint/Makefile.PL.include' or die $@) unless -f 'META.yml'; |
11 | |
12 | WriteMakefile(...); |
13 | |
14 | `maint/Makefile.PL.include`: |
15 | |
f12b221f |
16 | BEGIN { -e 'Distar' or system qw(git clone https://github.com/p5sagit/Distar.git) } |
054577ba |
17 | use lib 'Distar/lib'; |
18 | use Distar 0.001; |
19 | |
20 | author 'A. U. Thor <author@cpan.org>'; |
21 | |
22 | manifest_include t => 'test-helper.pl'; |
23 | manifest_include corpus => '.txt'; |
24 | |
25 | make commmands: |
26 | |
27 | $ perl Makefile.PL |
28 | $ make bump # bump version |
29 | $ make bump V=2.000000 # bump to specific version |
30 | $ make bumpminor # bump minor version component |
31 | $ make bumpmajor # bump major version component |
32 | $ make nextrelease # add version heading to Changes file |
33 | $ make releasetest # build dist and test (with xt/ and RELEASE_TESTING=1) |
34 | $ make preflight # check that repo and file state is release ready |
35 | $ make release # check releasetest and preflight, commits and tags, |
36 | # builds and uploads to CPAN, and pushes commits and |
37 | # tag |
38 | $ make release FAKE_RELEASE=1 |
39 | # builds a release INCLUDING committing and tagging, |
40 | # but does not upload to cpan or push anything to git |
41 | |
42 | # DESCRIPTION |
43 | |
44 | [ExtUtils::MakeMaker](https://metacpan.org/pod/ExtUtils%3A%3AMakeMaker) works well enough as development tool for |
45 | builting and testing, but using it to release is annoying and error prone. |
46 | Distar adds just enough to [ExtUtils::MakeMaker](https://metacpan.org/pod/ExtUtils%3A%3AMakeMaker) for it to be a usable dist |
47 | author tool. This includes extra commands for releasing and safety checks, and |
48 | automatic generation of some files. It doesn't require any non-core modules and |
49 | is compatible with old versions of perl. |
50 | |
51 | # FUNCTIONS |
52 | |
53 | ## author( $author ) |
54 | |
55 | Set the author to include in generated META files. Can be a single entry, or |
56 | an arrayref. |
57 | |
58 | ## manifest\_include( $dir, $pattern ) |
59 | |
60 | Add a pattern to include files in the MANIFEST file, and thus in the generated |
61 | dist files. |
62 | |
63 | The pattern can be either a regex, or a path suffix. It will be applied to the |
64 | full path past the directory specified. |
65 | |
66 | The default files that are always included are: `.pm` and `.pod` files in |
67 | `lib`, `.t` files in `t` and `xt`, `.pm` files in `t/lib` and `xt/lib`, |
68 | `Changes`, `MANIFEST`, `README`, `LICENSE`, `META.yml`, and `.PL` files in |
69 | the dist root, and all files in `maint`. |
70 | |
71 | # AUTOGENERATED FILES |
72 | |
73 | - `MANIFEST.SKIP` |
74 | |
75 | The `MANIFEST.SKIP` will be automatically generated to exclude any files not |
76 | explicitly allowed via `manifest_include` or the included defaults. It will be |
77 | created (or updated) at `perl Makefile.PL` time. |
78 | |
79 | - `README` |
80 | |
81 | The `README` file will be generated at dist generation time, inside the built |
82 | dist. It will be generated using `pod2text` on the main module. |
83 | |
84 | If a `README` file exists in the repo, it will be used directly instead of |
85 | generating the file. |
86 | |
87 | # MAKE COMMMANDS |
88 | |
89 | ## test |
90 | |
91 | test will be adjusted to include `xt/` tests by default. This will only apply |
92 | for authors, not users installing from CPAN. |
93 | |
94 | ## release |
95 | |
96 | Releases the dist. Before releasing, checks will be done on the dist using the |
97 | `preflight` and `releasetest` commands. |
98 | |
99 | Releasing will generate a dist tarball and upload it to CPAN using cpan-upload. |
100 | It will also create a git tag for the release, and push the tag and branch. |
101 | |
102 | ### FAKE\_RELEASE |
103 | |
104 | If release is run with FAKE\_RELEASE=1 set, it will skip uploading to CPAN and |
105 | pushing to git. A release commit will still be created and tagged locally. |
106 | |
107 | ## preflight |
108 | |
109 | Performs a number of checks on the files and repository, ensuring it is in a |
110 | sane state to do a release. The checks are: |
111 | |
112 | - All version numbers match |
113 | - The `MANIFEST` file is up to date |
114 | - The branch is correct |
115 | - There is no existing tag for the version |
116 | - There are no unmerged upstream changes |
117 | - There are no outstanding local changes |
118 | - There is an appropriate staged Changes heading |
119 | - cpan-upload is available |
120 | |
121 | ## releasetest |
122 | |
123 | Test the dist preparing for a release. This generates a dist dir and runs the |
124 | tests from inside it. This ensures all appropriate files are included inside |
125 | the dist. `RELEASE_TESTING` will be set in the environment. |
126 | |
127 | ## nextrelease |
128 | |
129 | Adds an appropriate changelog heading for the release, and prompts to stage the |
130 | change. |
131 | |
132 | ## bump |
133 | |
134 | Bumps the version number. This will try to preserve the length and format of |
135 | the version number. The least significant digit will be incremented. Versions |
136 | with underscores will preserve the underscore in the same position. |
137 | |
138 | Optionally accepts a `V` option to set the version to a specific value. |
139 | |
140 | The version changes will automatically be committed. Unstaged modifications to |
141 | the files will be left untouched. |
142 | |
143 | ### V |
144 | |
145 | The V option will be passed along to the version bumping script. It can accept |
146 | a space separated list of options, including an explicit version number. |
147 | |
148 | Options: |
149 | |
150 | - --force |
151 | |
152 | Updates version numbers even if they do not match the current expected version |
153 | number. |
154 | |
155 | - --stable |
156 | |
157 | Attempts to convert the updated version to a stable version, removing any |
158 | underscore. |
159 | |
160 | - --alpha |
161 | |
162 | Attempts to convert the updated version to an alpha version, adding an |
163 | underscore in an appropriate place. |
164 | |
165 | ## bumpminor |
166 | |
167 | Like bump, but increments the minor segment of the version. This will treat |
168 | numeric versions as x.yyyzzz format, incrementing the yyy segment. |
169 | |
170 | ## bumpmajor |
171 | |
172 | Like bumpminor, but bumping the major segment. |
173 | |
174 | ## refresh |
175 | |
176 | Updates Distar and re-runs `perl Makefile.PL` |
177 | |
178 | # SUPPORT |
179 | |
180 | IRC: #web-simple on irc.perl.org |
181 | |
182 | Git repository: [git://git.shadowcat.co.uk/p5sagit/Distar](git://git.shadowcat.co.uk/p5sagit/Distar) |
183 | |
184 | Git browser: [http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit/Distar.git;a=summary](http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit/Distar.git;a=summary) |
185 | |
186 | # AUTHOR |
187 | |
188 | mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk> |
189 | |
190 | # CONTRIBUTORS |
191 | |
192 | haarg - Graham Knop (cpan:HAARG) <haarg@cpan.org> |
193 | |
194 | ether - Karen Etheridge (cpan:ETHER) <ether@cpan.org> |
195 | |
196 | frew - Arthur Axel "fREW" Schmidt (cpan:FREW) <frioux@gmail.com> |
197 | |
198 | Mithaldu - Christian Walde (cpan:MITHALDU) <walde.christian@googlemail.com> |
199 | |
200 | # COPYRIGHT |
201 | |
202 | Copyright (c) 2011-2015 the Distar ["AUTHOR"](#author) and ["CONTRIBUTORS"](#contributors) |
203 | as listed above. |
204 | |
205 | # LICENSE |
206 | |
207 | This library is free software and may be distributed under the same terms |
208 | as perl itself. See [http://dev.perl.org/licenses/](http://dev.perl.org/licenses/). |