Discuss the patch online until it feels ready to merge.
Make sure the patch comes with tests if applicable.
Update the git-svn repository
git svn fetch
git svn rebase
Fetch the patch and apply it to the git-svn repository.
For a github pull request https://github.com/ocaml/ocaml/pull/{N}
I do
wget https://github.com/ocaml/ocaml/pull/{N}.patch
git am -3 {N}.patch
For an arbitrary patch foo.patch
on my filesystem,
git apply --reject foo.patch
Rebase the patch series
into a few well-separated, self-contained patches (github PRs can generate gazillions of micro-changes)
erasing history that does not make sense after the issue is merged (back-and-forth between different designs, etc. The PR number allows interested people to go back to the original discussion if needed.)
bisectable: the distribution should be in a good state after the application of each patch (in particular, later commits that fix bugs in previous commits should always be squashed into the commit they fix)
with readable commit messages (this is for future developers needing to understand a change that happened in the past). Commit messages should not overflow 80 columns, with the following format:
{one-liner header description (with issue number if applicable)}
{blank line}
{one or several paragraphs of explanation if needed}
Write a Changelog entry:
in the right section (named sections if major feature, generic "Bug fixes" and "Feature requests" otherwise)
using the label "*
" if it breaks existing programs, "-
" otherwise
with the issue number PR#{N}
if from mantis, GPR#{N}
if from github
(several numbers separated by commas can be used)
with a concise readable description of the change (possibly taken from a commit message, but it should make sense to end-users reading release notes)
crediting the people that worked on the feature
I personally use "and" as a separator between equally-important contributions and "," for decreasing importance; no hard convention, though.
The people that wrote the code should be credited of course, but also substantial code reviews or design advice, and the reporter of the bug (if applicable) or designer of the feature request (if novel).
The only reasons not to write a changelog would be that it's really a trivial typo, or that it fixes a problem in trunk that was never exposed in a release. But if external contributors saw the problem and fixed it, it was likely exposed one way or another.
following the format
{label} {issue number(s)}: {readable description}
({credits})
note that the {credits}
should be on their own line, aligned with the
issue number for readability
({readable description}
can be multiline to not overflow 80
columns, and should be aligned with the issue number as well.)
This changelog work can be amended to the user's patch (if it's just one patch) or as a separate commit (if it's a patch series and no particular commit feels best suited to receive the Changelog entry.
(Do not under-estimate the importance of a good changelog. Users do read the release notes, and things forgotten from the changelog will cause pain or regrets down the line.)
Edit the patch series' commit messages to preserve author information
SVN will erase the committer name at merge time. My convention to retain authorship information is to use the following format for commit messages:
{one-liner header description (with issue number if possible)}
{blank line}
({author name})
{blank line}
{one or several paragraphs of explanation if needed}
The {author name}
can be just the full name of the author, or
sometimes "(Patch by {full name}
)". If an author is known only by
his mantis or github pseudonym, I use "{pseudonym}
" or "user
'{pseudonym}
'" as full name.
(git-svn
has an option --add-author-from
that inserts a credit
line at the same place in the commit message, using a different
format. I found it inconvient however to use it reliably when
merging patch series, as there are often commit of mine in the mix
that don't need this extra information, so hand-editing each commit
message is my preferred method.)
make world.opt
and check that the testsuite still passes
make tests
If a specific test testsuite/tests/{foo}
was broken by a previous iteration,
it can be tested in isolation with
cd testsuite
make one DIR=tests/foo
To understand a failure, go to testsuite/tests/foo
and compare
the .result
files to their corresponding .reference
files.
Commit the patch series
git svn dcommit
If you are subscribed to the CI, watch for angry emails from
ci.inria.fr
telling you that you broke stuff (typically: on 32
bits systems, or under MSVC).