Hmm, I don't like the side effect of merging from upstream: the merge "activity" appears in other people's PR on GitHub web UI.

Example screenshot:

It's quite noisy when viewing PRs. Rebasing is a cleaner approach IMO.
But if everyone else is ok with merging, then I'm fine with it.

Hmm, I don't like the side effect of merging from upstream: the merge "activity" appears in other people's PR on GitHub web UI.

Would you please link? I want to confirm what happened there.

It may be better to recommend to new contributors that they should be developing on a branch in their account for each feature. As for rebase, I rarely usegit pull orgit merge when working with repos on GitHub. I have taught the following workflow to new open source contributors for years with good success:https://www.slideshare.net/willingc/yes-you-can-git It uses agit fetchgit rebase approach to reduce merge conflicts for new users.

I don't object to adding a note for new contributors about rebase though.

It uses agit fetchgit rebase approach to reduce merge conflicts for new users.

git rebase doesn't reduce conflict. It even increase conflict sometime.

git rebase doesn't reduce conflict. It even increase conflict sometime.

@methane The explicit git fetch/git rebase combined with specific remote naming, branch usage, and update ordering approach that I teach does reduce merge conflicts significantly.

However, I do agree with you that using rebase when not following the particular workflow that I use can have unexpected results.

I recommend a few things for this section:

• At the top of the bootcamp file, add a note stating that it is recommended that new users of git and GitHub understand how to create a pull request and resolve merge conflicts.
• In the above note, state explicitly that the Git Bootcamp commands reflect one way, though not the only way, to use git and GitHub.
• Make the changes suggested in this PR.
• Add a note in the changed sections to state that some contributors way choose to usegit fetch/ git rebase instead ofgit pull/git merge. Git pull is acombination of git fetch and git merge andgit merge. If using rebase, following theGolden Rule of Rebasing,Do not rebase commits that exist outside your repository and people may have based work on them., is very important.

As@asvetlov mentions, it doesn't really matter since we squash.

the revised doc matches what I do and have done successfully, as a git non-expert, for 2 years.

Good to hear@terryjreedy. I'll approve this PR as stands and add the other notes in a separate PR.

FWIW, I leave two comments about why I think merge is better.

If the guide is for contributing to general OSS, it is recommended to keep commits in the pull request branch clean. That's why many people recommend rebase. But we're using "Squash and merge" workflow, cleaning commits in pull request branch is not so important. Keeping history clean is complex than just using merge.

When people are expert and keep history in the branch clean withcommit --amend andrebase -i,git rebase origin/master may be easy asgit merge origin/master. But when people change same part of the code several times and the same part is changed inorigin/master too,git rebase origin/master forces the user to resolve conflict several times.

There are many documents aboutgit rebase andmerge on the internet. In our document, let's focus on people using git only for contributing to cpython.

And github creates much noise whenrebase && push -f is used. I don't know why.

@Mariatta I found the issue you reported. And it may be caused byrebase workflow!

See this log:https://github.com/ma8ma/cpython/commits/9e1425d3d9249f89850274b99c2178b29c9064f6?after=9e1425d3d9249f89850274b99c2178b29c9064f6+349

After 3.8a1 is released, ma8ma creates different commit object (see "ma8ma committed" in the history).
Why? I don't know. But note that master branch is not straight. See this graph:

Maybe,git pull --rebase upstream/master accidentally create "straight" commit graph. And ma8ma might usegit push -f origin master, as the previous devguide said. But I'm not sure.

Anyway, merge workflow doesn't create such "rewrote" commits.

Huh, very interesting.. Alright. Thanks for following through with this,@methane.