GettingStarted
So, you've cloned the main Moose repository to your local machine (see "Get the Code") and you're ready
to do some hacking. We couldn't be happier to welcome you to our community!
Of course, to ensure that your first experience is as productive and satisfying as possible, you should
probably take some time to read over this entire POD document. Doing so will give you a full
understanding of how Moose developers and maintainers work together and what they expect from one
another. Done? Great!
Next, assuming you have a GitHub account, go to <http://github.com/moose/Moose> and forktherepository
(see <https://help.github.com/articles/fork-a-repo>). This will put an exact replica of the Moose
repository into your GitHub account, which will serve as a place to publish your patches for the Moose
maintainers to review and incorporate.
Once your fork has been created, switch to your local working repository directory and update your
"origin" remote's push URL. This allows you to use a single remote ("origin") to both pull in the latest
code from GitHub and also push your work to your own fork:
# Replace YOUR_USERNAME below with your GitHub username
git remote set-url --push origin git@github.com:YOUR_USERNAME/moose.git
You can verify your work:
$ git remote -v
origin git@github.com:moose/Moose.git (fetch)
origin git@github.com:YOUR_USERNAME/moose.git (push)
Now, you're ready for action! From now on, you just follow the "Development Workflow" to publish your
work and submitpullrequests to the Moose Cabal.
DevelopmentWorkflow
The general gist of the STANDARDWORKFLOW is:
1. Update your local repository with the latest commits from the official repository
2. Create a new topic branch, based on the master branch
3. Hack away
4. Commit and push the topic branch to your forked repository
5. Submit a pull request through GitHub for that branch
What follows is a more detailed rundown of that workflow. Please make sure to review and follow the steps
in the previous section, "Getting Started", if you have not done so already.
UpdateYourRepository
Update your local copy of the master branch from the remote:
git checkout master
git pull --rebase
CreateYourTopicBranch
Now, create a new topic branch based on your master branch. It's useful to use concise, descriptive
branch names such as: pod-syntax-contrib, feat-autodelegation, patch-23-role-comp, etc. However, we'll
just call ours "my-feature" for demonstration purposes:
git checkout -b topic/my-feature
Hack.Commit.Repeat.
While you're hacking, the most important thing to remember is that your topic branch is yours to do with
as you like. Nothing you do there will affect anyone else at this point. Commit as often as little or as
often as you need to and don't let perfection get in the way of progress. However, don't try to do too
much as the easiest changes to integrate are small and focused.
If it's been a while since you created your topic branch, it's often a good idea to periodically rebase
your branch off of the upstream master to reduce your work later on:
git fetch # or, git remote update
git rebase origin/master # or, git pull --rebase origin master
You should also feel free to publish (using "push --force" if necessary) your branch to your GitHub fork
if you simply need feedback from others. (Note: actual collaboration takes a bit more finesse and a lot
less "--force" however).
CleanUpYourBranch
Finally, when your development is done, it's time to prepare your branch for review. Even the smallest
branches can often use a little bit of tidying up before they are unleashed on a reviewer.
Clarifying/cleaning up commit messages, reordering commits, splitting large commits or those which
contain different types of changes, squashing related or straggler commits are all highly worthwhile
activities to undertake on your topic branch.
Remember: Your topic branch is yours. Don't worry about rewriting its history or breaking fast-forward.
Some useful commands are listed below but please make sure that you understand what they do as they can
rewrite history:
- git commit --amend
- git rebase --interactive
- git cherry-pick
Ultimately, your goal in cleaning up your branch is to craft a set of commits whose content and messages
are as focused and understandable as possible. Doing so will greatly increase the chances of a speedy
review and acceptance into the mainline development.
RebaseontheLatest
Before your final push and issuing a pull request, you need to ensure that your changes can be easily
merged into the master branch of the upstream repository. This is done by once again rebasing your branch
on the latest "origin/master".
git fetch # or, git remote update
git rebase origin/master # or, git pull --rebase origin master
PublishandPullRequest
Now it's time to make your final push of the branch to your fork. The "--force" flag is only necessary if
you've pushed before and subsequently rewriting your history:
git push --force
After your branch is published, you can issue a pull request to the Moose Cabal. See
<https://help.github.com/articles/using-pull-requests> for details.
Congratulations! You're now a contributor!
ApprovalWorkflow
Moose is an open project but it is also an increasingly important one. Many modules depend on Moose being
stable. Therefore, we have a basic set of criteria for reviewing and merging branches. What follows is a
set of rough guidelines that ensures all new code is properly vetted before it is merged to the master
branch.
It should be noted that if you want your specific branch to be approved, it is your responsibility to
follow this process and advocate for your branch.
Small bug fixes, doc patches and additional passing tests.
These items don't really require approval beyond one of the core contributors just doing a simple
review. For especially simple patches (doc patches especially), committing directly to master is
fine.
Larger bug fixes, doc additions and TODO or failing tests.
Larger bug fixes should be reviewed by at least one cabal member and should be tested using the
xt/author/test-my-dependents.t test.
New documentation is always welcome, but should also be reviewed by a cabal member for accuracy.
TODO tests are basically feature requests, see our "New Features" section for more information on
that. If your feature needs core support, create a "topic/" branch using the "Development Workflow"
and start hacking away.
Failing tests are basically bug reports. You should find a core contributor and/or cabal member to
see if it is a real bug, then submit the bug and your test to the RT queue. Source control is not a
bug reporting tool.
New user-facing features.
Anything that creates a new user-visible feature needs to be approved by morethanone cabal member.
Make sure you have reviewed "New Features" to be sure that you are following the guidelines. Do not
be surprised if a new feature is rejected for the core.
New internals features.
New features for Moose internals are less restrictive than user facing features, but still require
approval by atleastone cabal member.
Ideally you will have run the xt/author/test-my-dependents.t script to be sure you are not breaking
any MooseX module or causing any other unforeseen havoc. If you do this (rather than make us do it),
it will only help to hasten your branch's approval.
Backwards incompatible changes.
Anything that breaks backwards compatibility must be discussed by the cabal. Backwards incompatible
changes should not be merged to master if there are strong objections from any cabal members.
We have a policy for what we see as sane "BACKWARDS COMPATIBILITY" for Moose. If your changes break
back-compat, you must be ready to discuss and defend your change.
ReleaseWorkflow
# major releases (including trial releases)
git checkout master
# minor releases
git checkout stable/X.YY
# do final changelogging, etc
git commit
dzil release # or dzil release --trial for trial releases
ReleaseHow-To
Moose uses Dist::Zilla to manage releases. Although the git repository comes with a "Makefile.PL", it is
a very basic one just to allow the basic "perl Makefile.PL && make && make test" cycle to work. In
particular, it doesn't include any release metadata, such as dependencies. In order to get started with
Dist::Zilla, first install it: "cpanm Dist::Zilla", and then install the plugins necessary for reading
the "dist.ini": "dzil authordeps | cpanm".
Moose releases fall into two categories, each with their own level of release preparation. A minor
release is one which does not include any API changes, deprecations, and so on. In that case, it is
sufficient to simply test the release candidate against a few different Perls. Testing should be done
against at least two recent major versions of Perl (5.8.8 and 5.10.1, for example). If you have more
versions available, you are encouraged to test them all. However, we do not put a lot of effort into
supporting older 5.8.x releases.
For major releases which include an API change or deprecation, you should run the
xt/author/test-my-dependents.t test. This tests a long list of MooseX and other Moose-using modules from
CPAN. In order to run this script, you must arrange to have the new version of Moose in Perl's include
path. You can use "prove -b" and "prove -I", install the module, or fiddle with the "PERL5LIB"
environment variable, whatever makes you happy.
This test downloads each module from CPAN, runs its tests, and logs failures and warnings to a set of
files named test-mydeps-$$-*.log. If there are failures or warnings, please work with the authors of the
modules in question to fix them. If the module author simply isn't available or does not want to fix the
bug, it is okay to make a release.
Regardless of whether or not a new module is available, any breakages should be noted in the conflicts
list in the distribution's dist.ini.
EmergencyBugWorkflow(forimmediaterelease)
The stable branch exists for easily making bug fix releases.
git remote update
git checkout -b topic/my-emergency-fix origin/master
# hack
git commit
Then a cabal member merges into "master", and backports the change into "stable/X.YY":
git checkout master
git merge topic/my-emergency-fix
git push
git checkout stable/X.YY
git cherry-pick -x master
git push
# release
ProjectWorkflow
For longer lasting branches, we use a subversion style branch layout, where master is routinely merged
into the branch. Rebasing is allowed as long as all the branch contributors are using "git pull --rebase"
properly.
"commit --amend", "rebase --interactive", etc. are not allowed, and should only be done in topic
branches. Committing to master is still done with the same review process as a topic branch, and the
branch must merge as a fast forward.
This is pretty much the way we're doing branches for large-ish things right now.
Obviously there is no technical limitation on the number of branches. You can freely create topic
branches off of project branches, or sub projects inside larger projects freely. Such branches should
incorporate the name of the branch they were made off so that people don't accidentally assume they
should be merged into master:
git checkout -b my-project--topic/foo my-project
(unfortunately Git will not allow "my-project/foo" as a branch name if "my-project" is a valid ref).
Install Now
Emojis
