Changes between Version 22 and Version 23 of TracDev/SubmittingPatches

Timestamp:

Sep 8, 2017, 2:32:27 AM (7 years ago)

Author:

Ryan J Ollos

Comment:

Document how to work from GitHub. Refs comment:1:ticket:12358.

TracDev/SubmittingPatches

@@ -115 +115 @@
 After that, depending on lots of factors, your patch will be reviewed and eventually integrated. Most likely, you'll be asked to rework your patch a bit, according to the preferences of the Trac maintainers. 
 
+== Multiple Changesets
+
+For work that requires more than a single changeset, or if you are simply more comfortable working from a Git or Mercurial, it can be easier to stage the changes in a DVCS repository fork. The following will discuss how to work from the [https://github.com/edgewall/trac GitHub mirror].
+
+1. [https://help.github.com/articles/fork-a-repo/ Fork the repository] to your own GitHub account. To keep your fork in sync you'll want to configure your repository to pull in upstream changes from the Trac mirror.
+{{{#!sh
+$ git clone https://github.com/rjollos/trac.git
+$ cd trac
+$ git remote add mirror https://github.com/edgewall/trac.git
+$ git branch -a
+* trunk
+  remotes/origin/0.11-stable
+  remotes/origin/0.12-stable
+  remotes/origin/1.0-stable
+  remotes/origin/1.2-stable
+  remotes/origin/HEAD -> origin/trunk
+  remotes/origin/trunk
+# Add remote tracking branches, as needed
+$ git branch -b 1.2-stable origin/1.2-stable
+Branch 1.2-stable set up to track remote branch 1.2-stable from origin.
+$ git branch
+  1.2-stable
+* trunk
+}}}
+1. Create a local topic branch to work from. It's useful to use the ticket number as a prefix when naming the branch (e.g. `t12905`). Be sure to base your work on the branch that the ticket is targeted against, e.g. `1.2-stable` or `trunk`. Never commit directly to a remote tracking branch (i.e. `trunk` or one of the `-stable` branches), as you'll need to pull upstream changes to those branches for rebasing your topic branch or creating new topic branches.
+{{{#!sh
+$ git status -sb
+## trunk...origin/trunk
+$ git checkout -b t12905_request_getfile
+# or if the current branch was not trunk
+$ git checkout -b t12905_request_getfile trunk
+}}}
+1. Do some work, staging your changes atomically. Use [https://help.github.com/articles/about-git-rebase/ interactive rebase] and `git add -p` to breakup large changeset into atomic commits. Finally, push your changes back to your !GitHub fork.
+{{{#!sh
+# Edit files
+$ git add -p
+$ git commit
+# Repeat edit, add, commit cycle as needed
+$ git push -u origin t12905_request_getfile
+}}}
+1. Publish your work to a Trac ticket. Please use a proper TracLink to adding a link to your topic branch, rather than pasting the URL in a ticket comment (e.g. [https://github.com/rjollos/trac/commits/t12905_request_getfile.1 t12905_request_getfile.1]):
+{{{
+[https://github.com/rjollos/trac/commits/t12905_request_getfile.1 t12905_request_getfile.1]
+}}}
+1. If your topic branch has fallen behind the target branch for integration, you should rebase your work and publish it again to the ticket. Never rebase a published branch, instead rename your branch before rebasing it. A common convention is to append `.1`, `.2`, ... to the branch name. Rebasing is preferred to merging, as a rebased branch is cleaner and easier to integrate upstream.
+ {{{#!sh
+$ git rev-parse --abbrev-ref HEAD
+t12905_request_getfile.1
+$ git co trunk && git pull && git co -
+$ git branch -m t12905_request_getfile.2
+$ git rev-parse --abbrev-ref HEAD
+t12905_request_getfile.2
+$ git rebase trunk
+}}}
+ The same pattern should be followed if you need to revise a branch by editing commits (e.g. by interactive rebase). New changesets may be added to an already published branch, but the history of an already published branch must not be changed. A hint that you are changing the history of a published branch is the needed to use the `-f/--force` flag when `push`ing the branch to your remote origin.
+
+It's not necessary, or even helpful, to submit a pull request through the GitHub mirror, as the mirror is currently readonly. This may change in the future.
+
 ------
 See also: Mercurial:ContributingChanges#Patch_descriptions, TracDev/DevelopmentWorkflow.