Changes between Version 98 and Version 99 of HowToGit


Ignore:
Timestamp:
08/23/21 19:50:56 (4 years ago)
Author:
wenzeslaus
Comment:

Update mutliple commits section to current workflow, master to main, smaller updates

Legend:

Unmodified
Added
Removed
Modified

  • HowToGit

    v98 v99  
    33= Git How-to =
    44
     5**The instructions for the common contributing cases are in [https://github.com/OSGeo/grass/blob/main/CONTRIBUTING.md CONTRIBUTING] file.**
     6
    57The repo is here: https://github.com/OSGeo/grass
    6 
    7 **The instructions for the common contributing cases are in [https://github.com/OSGeo/grass/blob/master/CONTRIBUTING.md CONTRIBUTING] file.**
    88
    99Below we discuss more advanced and specific workflows.
    … …  
    2222 * Fork the GRASS GIS repository, create feature branch(es) with the changes, and suggest your changes using pull requests.
    2323
    24 === Workflow for GRASS GIS git repositories ===
    25 
    26 The same procedure is recommended also from [https://github.com/osgeo/grass-addons GRASS Addons repository].
    27 ==== Preparation: cloning the repo ====
     24== Workflow for GRASS GIS Git repositories ==
     25
     26The same procedure is recommended also for [https://github.com/osgeo/grass-addons GRASS Addons repository].
     27
     28=== Preparation: cloning the repo ===
    2829
    2930First [https://github.com/OSGeo/grass fork the GRASS GIS repo] in the !GitHub UI to `your_GH_account`. This is the same as what !GitHub documentation suggests. See: [https://help.github.com/en/articles/fork-a-repo Fork a repo] and [https://help.github.com/en/articles/syncing-a-fork Syncing a fork] in !GitHub help.
    3031
    31 Note: add SSH key, see [https://help.github.com/en/articles/connecting-to-github-with-ssh GitHub documentation].
     32Note: Add SSH key, see [https://help.github.com/en/articles/connecting-to-github-with-ssh GitHub documentation].
    3233
    3334Note: If you get the error message: [https://askubuntu.com/questions/610940/ssh-connect-to-host-github-com-port-22-connection-refused ''ssh: connect to host github.com port 22: Connection refused''] (e.g. because you are behind a firewall that blocks traffic on port 22), you can try to replace {{{git@github.com:}}} with {{{ssh://git@ssh.github.com:443/}}}, when you clone or remote add repos.
    … …  
    5657git remote add upstream git@github.com:OSGeo/grass-addons.git
    5758}}}
    58 ==== Working with git ====
     59=== Working with Git ===
    5960
    6061Note: this requires the "remotes" to be set as shown above.
    … …  
    6465git fetch --all
    6566
    66 ### a) updating MASTER
    67 # merge updates into local master
    68 git merge upstream/master
     67### a) updating the main branch
     68# merge updates into local main branch
     69git merge upstream/main
    6970
    7071# at this point we have reached:
    71 # (HEAD -> master, upstream/master)
     72# (HEAD -> main, upstream/main)
    7273
    7374### b) updating releasebranch_7_8
    … …  
    8485
    8586# update own remote
    86 # - clears "Your branch is ahead of 'origin/master' by XX commits.", and
    87 # - avoids "This branch is XX commits behind OSGeo:master." on GitHub web interface
    88 git push origin master
     87# - clears "Your branch is ahead of 'origin/main' by XX commits.", and
     88# - avoids "This branch is XX commits behind OSGeo:main." on GitHub web interface
     89git push origin main
    8990
    9091# list existing branches
    … …  
    114115}}}
    115116
    116 NOTE: for different pull requests, simply create different feature branches.
    117 
    118 ==== Keep your local source code up to date ====
     117Note: for different pull requests, simply create different feature branches.
     118
     119=== Keep your local source code up to date ===
    119120
    120121[from https://github.com/OSGeo/gdal/blob/master/CONTRIBUTING.md#working-with-a-feature-branch]
    121122
    122 You may need to resynchronize against master if you need some bugfix or new capability that has been added since you created your branch
     123You may need to re-synchronize against the main branch if you need some bugfix or new capability that has been added since you created your branch
    123124
    124125{{{
    125126# assuming that "upstream" points to OSGeo/grass
    126127git fetch upstream
    127 git rebase upstream/master
     128git rebase upstream/main
    128129
    129130# if rebase fails with "error: cannot rebase: You have unstaged changes...", then move your uncommitted local changes to "stash"
    130131git stash
    131132# now you can rebase
    132 git rebase upstream/master
     133git rebase upstream/main
    133134# apply your local changes on top
    134 git stash apply && git stash pop
     135git stash pop
    135136}}}
    136137
    137138Continue do your changes and commit/push them (ideally to a feature branch, see above).
    138139
    139 ==== Updating your PR from master ====
    140 
    141 Updating your PR from master is often referred to as rebasing a PR. It comes into play in case there are
    142 changes in master you need to incorporate into your (feature or fix) branch before the PR can be merged, you need to rebase your branch to upstream:
     140=== Updating your PR from main ===
     141
     142Updating your PR from the main branch is often referred to as rebasing a PR. It comes into play in case there are
     143changes in the main branch you need to incorporate into your (feature or fix) branch before the PR can be merged, you need to rebase your branch to upstream:
    143144
    144145{{{
    145146git fetch upstream
    146 git rebase upstream/master
     147git rebase upstream/main
    147148git status
    148149}}}
    … …  
    173174}}}
    174175
    175 If you have access to one of the OSGeo repositories (namelly OSGeo/grass in this case), before force pushing, you need be sure that origin points to your fork and not the OSGeo repo. You can check that using `git remote -v`.
     176If you have access to one of the OSGeo repositories (namely OSGeo/grass in this case), before force pushing, you need be sure that origin points to your fork and not the OSGeo repo. You can check that using `git remote -v`.
    176177== Switching between branches ==
    177178
    … …  
    180181https://lists.osgeo.org/pipermail/grass-dev/2019-May/092653.html
    181182
    182 == Testing pull requests from other contributors in master ==
     183== Testing pull requests from other contributors in main ==
    183184
    184185!GitHub provides command line instructions under each pull request ([https://github.com/OSGeo/grass/pulls "Pulls" tab]). Please check there.
    … …  
    228229{{{
    229230Fix this error #123
    230 Someone wants to merge 3 commits into OSGeo:master from Someone:fix-this-error
     231Someone wants to merge 3 commits into OSGeo:main from Someone:fix-this-error
    231232}}}
    232233the command would look like:
    … …  
    238239
    239240# after testing, you may delete locally
    240 git checkout master
     241git checkout main
    241242git branch -D fix-this-error
    242243}}}
    … …  
    247248[alias]
    248249        pr = "!f() { git fetch -fu ${2:-upstream} refs/pull/$1/head:pr/$1 && git checkout pr/$1; }; f"
    249         pr-clean = "!git checkout master ; git for-each-ref refs/heads/pr/* --format=\"%(refname)\" | while read ref ; do branch=${ref#refs/heads/} ; git branch -D $branch ; done"
     250        pr-clean = "!git checkout main ; git for-each-ref refs/heads/pr/* --format=\"%(refname)\" | while read ref ; do branch=${ref#refs/heads/} ; git branch -D $branch ; done"
    250251}}}
    251252
    … …  
    256257
    257258git branch -a
    258   master
     259  main
    259260* pr/832
    260261  pr/837
    … …  
    266267}}}
    267268
    268 Note: to be on the safe side, only use this for testing pull request!
     269Note: To be on the safe side, only use this for testing pull request!
    269270
    270271== Fixing bugs in a release branch ==
    … …  
    328329}}}
    329330
    330 === Backporting of a single commit from master to release branch ===
     331=== Backporting of a single commit from main to release branch ===
    331332
    332333Assumptions:
    … …  
    361362}}}
    362363
    363 Second, get commit hash from !GitHub or //git log// in master.
    364 
    365 Third, cherry-pick the change from master into the branch:
     364Second, get commit hash from !GitHub or //git log// in the main branch.
     365
     366Third, cherry-pick the change from main into the branch:
    366367
    367368{{{
    … …  
    425426== Code review: generate a single diff for a PR with multiple commits ==
    426427
    427 To speed up reviewing of a PR with multiple commits by reading a single diff file, you may diff the branch against the branch origin point. For example, if you PR 28 is on local branch pr_28, branched from master, you can do:
     428To speed up reviewing of a PR with multiple commits by reading a single diff file, you may diff the branch against the branch origin point. For example, if you PR 28 is on local branch pr_28, branched from the main branch, you can do:
    428429
    429430{{{
    … …  
    431432
    432433# note: with the three dots, it will only show diffs from changes on your side:
    433 git diff master...
     434git diff main...
    434435}}}
    435436
    … …  
    452453=== PR with multiple commits ===
    453454
    454 **Proposed**: it is a good idea to try to squash the accumulated commits in a PR before merging, especially if those are trivial fixes.
    455 
    456 As an example, PRxx contains 5 commits. Esp. in case that several commits of them are trivial fixes that only add noise to the history, "squashing" those results in a cleaner history and, among other things, makes it easier to use `git bisect` and `git blame`.
    457 
    458 Importantly, not always commits of each and every PR need to be squashed before merging. When extensive changes are being made, it often makes sense to keep them unsquashed (e.g. to make reviewing easier), but trivial fixes should still be squashed to the main commits.
    459 
    460 === Citing co-authors in a git commit message ===
    461 
    462 For co-authors, it is suggested using `Co-authored-by` at the end of the commit message:
     455All commits for a PR are squashed into one commit when merging to the base branch (that is usually the main branch). If the individual commit messages are not usable as is for the commit message of this new commit, modify the PR description so that it is usable as a commit message when maintainers merge the PR.
     456
     457You can have multiple commits in a PR or squash them depending on what you see as most appropriate, but usually multiple commits help certain aspects of the review.
     458
     459=== Citing co-authors in a Git commit message ===
     460
     461For co-authors, it is suggested using `Co-authored-by` at the end of the commit message with this syntax:
    463462
    464463{{{
    … …  
    474473 * GDAL contributing: https://github.com/OSGeo/gdal/blob/master/CONTRIBUTING.md
    475474 * Splitting a subfolder out into a new repository: https://help.github.com/en/github/using-git/splitting-a-subfolder-out-into-a-new-repository
     475 * [wiki:Submitting/General#Commitmessages Submitting guidelines: Commit messages]