My Dist::Zilla and git/GitHub workflow
There has been a bit of discussion recently on the #distzilla IRC channel about how people are integrating their CPAN distribution development with Git, and in particular some of the Dist::Zilla Git plugin(s). I thought it might contribute to a useful discussion if I show how I have things set up.
Like many, I want to host my code on GitHub and then periodically publish to CPAN. Dist::Zilla helps in both these by providing plugins to automatically push releases to GitHub, and then also upload to CPAN.
What bothers some is the stage at which these things happen, and also how the branches and tags are represented on GitHub. In particular, folks might want:
- a "clean" git branch which tracks CPAN releases
- another branch which is the "trunk" of development
- a user browsing the GitHub website to see the CPAN branch (with the README, etc)
- sane commit messages and tags
What I have configured is for the master branch on GitHub to be the one tracking CPAN releases. This makes it straightforward for most people to fork the distribution and tinker around without getting into trouble (i.e. they can build the dist).
My trunk of development takes place in a branch called devel, and that is from where I kick off Dist::Zilla builds and releases:
Tags are applied to the master branch automatically, with the version number which was uploaded to CPAN. So a user can again browse to GitHub, and when selecting a (version) tag they will see the CPAN dist at that version.
The commit message for the the master branch is also automatic, and contains the text of the latest section in the Changes file. Commit messages along my devel branch are of couse the everyday notes I make as I code. But following a Dist::Zilla driven release, one commit is done automatically on the devel branch to store the new header in the Changes file, and it gets the comment "Bumped changelog following rel. v%v".
Okay, this is all a bit abstract, so if you follow this link you can see the network graph for one of my modules. It clearly shows the two branches, how they are merged, and all commit messages.
I think this setup is really neat and tidy, and very intuitive for the visiting user who might not be familiar with Dist::Zilla. It's also almost completely automated so I really just stick to the devel branch and forget all about the rest.
Finally, let's look at a snippet from my dist.ini which drives it all. Note that the CommitBuild Plugin must come before the @Git Bundle:
[Git::CommitBuild]
branch =
release_branch = master
message = <contents of latest changelog entry>
[@Git]
commit_msg = Bumped changelog following rel. v%v
The CommitBuild Plugin is responsible for pushing the built distribution into a branch other than the one I've currently checked out. That is, I'm working in devel but the baked distribution is committed to master along with a nice comment, just at the same time as being uploaded to CPAN.
Okay, I have one confession. Getting the contents of the Changes file entry into that message variable does involve a wee hack, but you could equally just say something like "product of release %v" using the Git Plugin substitution variables.
I hope showing this has helped.
Computer Networks is my business, so Perl is my glue.
Interesting post thanks
There’s only one problem I’ve found with the “build” branch being the default on github: 1. When somebody forks your dist, that is the branch that gets forked. 2. People are inclined to patch the built branch, not the source tree 3. Re-applying commits made to the build branch to the source branch tends to be difficult, and you end up re-writing the contributors commits by hand yourself. This is fine and dandy unless you want their name in the commit logs =), and it is a bit of extra work.
Fair point about using the CPAN release branch as the default and the issues it causes. I think we are stuck either way: either the contributor sends a patch against the “wrong” branch as you say, or I require them to be familiar with Dist::Zilla to use my devel branch.
I would probably rather receive patches I have to work on a little than put off my users. But then again I’m not exactly drowning under a flood of contributions so perhaps I’ll change my mind one day in the future :-)
Hey, Oliver.
Could you please add some instructions on how to get started?
For a Dist:Zilla newbie, how do I begin with your bundle? I mean, I’m not even clear on what a bundle is.
Do I install your module and it configures everything?