stop recommend rebase for new contributors

[methane]

We should not recommend "rebase" and "push -f" to new users.

These command requires high skill when they cause trouble.

[asvetlov]

I think it makes sense.
We squash on merging anyway

[methane]

Could anyone check my English?

• happens vs happened
• "happens, " -- this comma is usual?
• "for how to..." -- is this usual wording?

[freddrake]

• You're using "happens" correctly.

• The common after "happens" is a typical usage.

• I'd say something more like "See these articles about resolving conflicts:". The "for how to" is a little awkward.

[methane]

Thanks!

[Mariatta]

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.

[methane]

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.

[willingc]

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 use git pull or git 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 a git fetchgit rebase approach to reduce merge conflicts for new users.

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

[methane]

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

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

[willingc]

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 use git fetch/ git rebase instead of git pull/git merge. Git pull is a combination of git fetch and git merge and git merge. If using rebase, following the Golden 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.

[terryjreedy]

If I have ever used rebase, it was because my fork and local repository was ahead or beside upstream. For normal updates when behind, I fetch and merge to each workspace, and to PR branches when working on them. I only get merge conflicts in idlelib when an old PR branch touches code affected by a different merged PR.

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

[willingc]

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.

[methane]

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 with commit --amend and rebase -i, git rebase origin/master may be easy as git merge origin/master. But when people change same part of the code several times and the same part is changed in origin/master too, git rebase origin/master forces the user to resolve conflict several times.

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

[methane]

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

[methane]

@Mariatta I found the issue you reported. And it may be caused by rebase 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 use git push -f origin master, as the previous devguide said. But I'm not sure.

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

[Mariatta]

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