Re: [PATCH v2] MyFirstContribution: Document --range-diff option when writing v2
- From
Glen Choo <chooglen@google.com>
- Date
- Sep 21, 2021, 17:58 UTC
- Message-ID
- <kl6ltuidlsjm.fsf@chooglen-macbookpro.roam.corp.google.com>
- In-Reply-To
- <00f94ddf-7019-a5e0-8fd5-a88a4b1cc5c3@gmail.com>
Bagas Sanjaya <bagasdotme@gmail.com> writes:
Show 23 quoted lines
>> +We'll reuse our `psuh` topic branch for v2. Before we make any changes, we'll >> +mark the tip of our v1 branch for easy reference: >> >> -When you're ready with the next iteration of your patch, the process is fairly >> -similar. >> +---- >> +$ git checkout psuh >> +$ git branch psuh-v1 >> +---- >> > > Alternatively we can branch off psuh-v2 from the original psuh: > ---- > $ git checkout psuh > $ git checkout -b psuh-v2 > ---- > > The original psuh thus become v1. To easily identify it, we can run: > ---- > $ git checkout psuh > $ git branch -M psuh-v1 > ---- >
I proposed to reuse the topic branch at the suggestion of Junio.
I do not think it is a good suggestion at all to use a new topic branch, especially a one that forked from the tip of the original submission, and work on that branch to produce the new round. It would be much better to create a topic branch or a lightweight tag "psuh-v1" that points at the old tip and keep working on the same branch. But that is a separate story.
Your suggested workflow is acutally fairly similar to the one I actually use. To keep this doc clear though, I think that we should probably propose just one workflow.
Show 5 quoted lines
> For completeness, we can say "Make your changes with `git rebase -i`. > Actions that you have to select in the todo editor of rebase depend on > reviewers' comments. For example, if they asked to squash a commit into > previous one, say `pick` on the latter and `squash` on the former." >
I hesitate to add a "rebase -i" tutorial because this document doesn't contain similar tutorials/explanations for any 'regular' Git workflow commands; the explanations are generally focused on mailing list-specific commands like "send-email" and "format-patch".
It seems unlikely to me that an aspiring contributor to Git would be unfamiliar with "rebase -i". It's not the most simple command, but it is common. In fact, because it is not so simple, it seems unlikely that we would do it justice in this document. For those who need it, additional reading on "rebase -i" can be left as an exercise to the reader.
>> +The `-v2` parameter tells `format-patch` to output "v2" patches. For instance, > > More accurately, `-v 2` marks the patchset as second iteration of it. >
Good point. I was stuggling with how to word this paragraph. I'll work that wording into this line.