Contributing changes to the CPAN6 papers

The preferred form for changes is patches, similar to the ones made by git-format-patch. There's nothing magic about this, it's just;

Subject: [PATCH] A one-line summary of the change

A description of the change, possibly including a description of why
the change is necessary, and why this change fixes the problem.

---

# diff output

If you attach the patch, please try to make sure your mail client sets the attachment to display inline.

Sending changes to the list before they are applied ensures that each change has a chance to be reviewed and discussed before it becomes part of the permanent project history, and engages the list participants in the changes.

The primary location for the cpan6 papers is:

git://git.cpan6.org/cpan6-papers

The changes are browsable via gitweb.

To fetch from a git:// URL, you need a version control client that can support the Git protocol. Cogito is recommended as a reasonable starting point, and examples will use cg- commands. I will also give examples using Stacked Git. However, you might prefer to use darcs-git, help clkao finish SVN::Mirror::Git, or maybe you're crazy enough to use Linus' git-core tools directly.

The command, using cogito, to get a copy of the cpan6 papers is:

cg-clone git://git.cpan6.org/cpan6-papers

This will download about 900kb (currently) of packfile; this is the complete history of the project. It is similar to svk mirror and svk sync in one quick command.

If you are only interested in making one submission, you can also just download the head tarball and send your changes as a patch against it.

If you would like to have a VCS flamewar, please do not do it on any of the cpan6.org mailing lists. The IRC channel (#cpan6 on irc.freenode.net) is open all hours for that kind of timewasting.

As you have a copy of the repository, you can make changes in your sand-box as you see fit. This page has brief instructions for Cogito and Stacked Git. If you would like to contribute instructions for $your_vcs, they can be added here as well.

First, you will need to tell the git plumbing who you are. You do not need to ask anyone for commit access, but you should put in your .profile or similar this information required for all Git porcelain:

GIT_AUTHOR_NAME="Your Name"
GIT_AUTHOR_EMAIL="you@example.com"
GIT_COMMITTER_NAME=$GIT_AUTHOR_NAME
GIT_COMMITTER_EMAIL=$GIT_AUTHOR_EMAIL

Then, you can go ahead and make some commits to your local repository:

# make a branch for your changes based on upstream
cg-switch -r master mine
# or: stg branch -c mine master

# hackhackhack

# save your changes locally - previewing the changes
cg-add file1 file2 ...
cg-commit -p
# or: stg new patch_name
#     stg add file1 file2
#     stg refresh

Assuming that you have made changes using the above commands, you can make patches with:

# now, make a patch file
cg-mkpatch -r origin > mine.patch
# or: stg mail -a -m --to pause6@lists.cpan6.org > mine.mbox

It's quite easy to manually turn this patch into an e-mail. Just put it in an e-mail, or attach it. If you do this, please try to put the subject from the patch into the e-mail Subject: header, and put [PATCH] at the start of the e-mail. This makes the list easier to scan over.

If you are sending more than a single patch for review, or you don't want to manually use your mail client, you can use git-format-patch

# take all changes since master, and write to individual files
git-format-patch master

git-send-email --to pause6@lists.cpan.org --smtp-server mail.example.com 0001-Change-Subject.txt

Stacked Git wins here:

stg mail -a --to pause6@lists.cpan6.org

If you make a bad commit that hasn't already been included upstream, you probably won't want to send people these mistakes. Using Cogito, you can use cg-admin-uncommit, or make a new branch with cg-switch and then use git-cherry-pick -rn 123ab (where 123ab is some significant part of the revision sha1 of the revision you are copying) to pull in the change to the new branch, and cg-commit -ec 123ab once you have revised the change to your satisfaction.

If you get confused, just fire up gitk --all and (hopefully) all will be revealed.

Anyway, this sort of thing is what Stacked Git is really good for; its commands are built around this use case. For instance:

# find out which patch you want to change
stg series

# go to it
stg pop --to patch_name

# ...edit the change...

# update the patch
stg refresh

# maybe check the files and look at the diff
stg files
stg diff -r /bottom

# now re-apply the remaining patches
stg push -a