Edgewall Software

Changes between Version 22 and Version 23 of TracDev/SubmittingPatches


Ignore:
Timestamp:
Sep 8, 2017, 2:32:27 AM (2 years ago)
Author:
Ryan J Ollos
Comment:

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

Legend:

Unmodified
Added
Removed
Modified
  • TracDev/SubmittingPatches

    v22 v23  
    115115After 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.
    116116
     117== Multiple Changesets
     118
     119For 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].
     120
     1211. [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.
     122{{{#!sh
     123$ git clone https://github.com/rjollos/trac.git
     124$ cd trac
     125$ git remote add mirror https://github.com/edgewall/trac.git
     126$ git branch -a
     127* trunk
     128  remotes/origin/0.11-stable
     129  remotes/origin/0.12-stable
     130  remotes/origin/1.0-stable
     131  remotes/origin/1.2-stable
     132  remotes/origin/HEAD -> origin/trunk
     133  remotes/origin/trunk
     134# Add remote tracking branches, as needed
     135$ git branch -b 1.2-stable origin/1.2-stable
     136Branch 1.2-stable set up to track remote branch 1.2-stable from origin.
     137$ git branch
     138  1.2-stable
     139* trunk
     140}}}
     1411. 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.
     142{{{#!sh
     143$ git status -sb
     144## trunk...origin/trunk
     145$ git checkout -b t12905_request_getfile
     146# or if the current branch was not trunk
     147$ git checkout -b t12905_request_getfile trunk
     148}}}
     1491. 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.
     150{{{#!sh
     151# Edit files
     152$ git add -p
     153$ git commit
     154# Repeat edit, add, commit cycle as needed
     155$ git push -u origin t12905_request_getfile
     156}}}
     1571. 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]):
     158{{{
     159[https://github.com/rjollos/trac/commits/t12905_request_getfile.1 t12905_request_getfile.1]
     160}}}
     1611. 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.
     162 {{{#!sh
     163$ git rev-parse --abbrev-ref HEAD
     164t12905_request_getfile.1
     165$ git co trunk && git pull && git co -
     166$ git branch -m t12905_request_getfile.2
     167$ git rev-parse --abbrev-ref HEAD
     168t12905_request_getfile.2
     169$ git rebase trunk
     170}}}
     171 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.
     172
     173It'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.
     174
    117175------
    118176See also: Mercurial:ContributingChanges#Patch_descriptions, TracDev/DevelopmentWorkflow.