docs/dev-manual/change-management.rst

   1 =================
   2 Change Management
   3 =================
   4
   5 This documentation assumes the reader is already familiary with using ``git``
   6 for managing file revisions.
   7
   8 .. contents::
   9    :local:
  10
  11 Getting started
  12 ===============
  13
  14 #.  Go to https://gitlab.com/gromacs/gromacs
  15
  16 .. todo:: Link to GitLab docs for setting up an account, setting up git, and cloning repositories.
  17
  18 Uploading a commit for review
  19 -----------------------------
  20
  21 Make sure your HEAD is up to date (use ``git pull --rebase origin`` if
  22 someone else has committed since you last pulled), check that your commit
  23 message follows the :doc:`commitstyle`.
  24
  25 Uploading a Work-In-Progress (WIP) or Private commit for review
  26 ---------------------------------------------------------------
  27
  28 .. todo:: Note work-in-progress and privacy semantics.
  29
  30 Code Review
  31 ===========
  32
  33 Reviewing someone else's uploaded commit
  34 ----------------------------------------
  35
  36 The reviewing workflow is the following:
  37
  38 #. https://gitlab.com/gromacs/gromacs/-/issues shows all open changes
  39 #. A change needs a +2 and usually +1 review, as well as a +2 verified
  40    to be allowed to be merged.
  41 #. Usually a patch goes through several cycles of voting, commenting and
  42    updating before it becomes merged, with votes from the developers indicating
  43    if they think that change hat progressed enough to be included.
  44 #. A change is submitted for merging and post-submit testing
  45    by clicking "Submit" by one of the main developers. This should be done by
  46    the reviewer after voting +2. After a patch is submitted it is
  47    replicated to the main git server.
  48
  49 Do not review your own code. The point of the policy is that at least
  50 two non-authors have voted +1, and that the issues are resolved in the
  51 opinion of the person who applies a +2 before a merge. If you have
  52 uploaded a minor fix to someone else's patch, use your judgement in
  53 whether to vote on the patch +1.
  54
  55 Guide for reviewing
  56 -------------------
  57
  58 -  First and foremost, check correctness to the extent possible;
  59 -  As portability and performance are the most important things (after
  60    correctness) do check for potential issues;
  61 -  Check adherence to the :ref:`GROMACS coding
  62    standards <style-guidelines>`;
  63 -  We should try to ensure that commits that implement bugfixes (as
  64    well as important features and tasks) get an `issue tracker`_ entry created
  65    and linked. The linking is done **automatically** through
  66    `special syntax <https://gitlab.com/help/user/markdown#special-gitlab-references>`__
  67 -  If the commit is a **bugfix**\ :
  68
  69    -  if present in the `issue tracker`_, it has to contain a valid reference to the
  70       issue;
  71    -  if it's a **major bug**, there has to be a bug report filed in the
  72       `issue tracker`_  (with urgent or
  73       immediate priority) and referenced appropriately.
  74
  75 -  If the commit is a **feature/task** implementation:
  76
  77    -  if it's present in the `issue tracker`_ it
  78       has to contain a valid reference to the issue;
  79    -  If no current issue is currently present and the change
  80       would benefit of one for future explanation on why it was
  81       added, a new issue should be created.
  82
  83 More git tips
  84 =============
  85
  86 .. rubric:: Q: Are there some other useful git configuration settings?
  87
  88 A: If you need to work with
  89 branches that have large
  90 differences (in particular, if a
  91 lot of files have moved), it can
  92 be helpful to set
  93
  94 ::
  95
  96     git config diff.renamelimit 5000
  97
  98 to increase the limit of inexact
  99 renames that Git considers. The
 100 default value is not sufficient,
 101 for example, if you need to do a
 102 merge or a cherry-pick from
 103 a release branch to master.
 104
 105 .. rubric:: Q: How do I use git rebase (also ``git pull --rebase``)?
 106
 107 A: Assume you have a local
 108 feature branch checked out, that
 109 it is based on master, and master
 110 has gotten new commits. You can
 111 then do
 112
 113 ::
 114
 115     git rebase master
 116
 117 to move your commits on top of
 118 the newest commit in master. This
 119 will save each commit you did,
 120 and replay them on top of master.
 121 If any commit results in
 122 conflicts, you need to resolve
 123 them as usual (including marking
 124 them as resolved using git add),
 125 and then use
 126
 127 ::
 128
 129     git rebase --continue
 130
 131 Note that unless you are sure
 132 about what you are doing, you
 133 should not use any commands that
 134 create or delete commits (git
 135 commit, or git checkout or git
 136 reset without paths). ``git rebase
 137 --continue`` will create the commit
 138 after conflicts have been
 139 resolved, with the original
 140 commit message (you will get a
 141 chance to edit it).
 142
 143 If you realize that the conflicts
 144 are too messy to resolve (or that
 145 you made a mistake that resulted
 146 in messy conflicts), you can use
 147
 148 ::
 149
 150     git rebase --abort
 151
 152 to get back into the state you
 153 started from (before the
 154 original git rebase master
 155 invocation). If the rebase is
 156 already finished, and you realize
 157 you made a mistake, you can get
 158 back where you started with
 159 (use git
 160 log <my-branch>@{1} and/or git
 161 reflog <my-branch> to check that
 162 this is where you want to go)
 163
 164 ::
 165
 166     git reset --hard <my-branch>@{1}
 167
 168 .. rubric:: Q: How do I prepare several commits at once?
 169
 170 A: Assume I have multiple independent changes in my working tree.
 171 Use
 172
 173 ::
 174
 175     git add [-p] [file]
 176
 177 to add one independent change at
 178 a time to the index. Use
 179
 180 ::
 181
 182     git diff --cached
 183
 184 to check that the index contains
 185 the changes you want. You can
 186 then commit this one change:
 187
 188 ::
 189
 190     git commit
 191
 192  If you want to test that the
 193 change works, use to temporarily
 194 store away other changes, and do
 195 your testing.
 196
 197 ::
 198
 199     git stash
 200
 201 If the testing fails, you can
 202 amend your existing commit with
 203 ``git commit --amend``. After you are
 204 satisfied, you can push the
 205 commit for review. If
 206 you stashed away your changes and
 207 you want the next change to be
 208 reviewed independently, do
 209
 210 ::
 211
 212     git reset --hard HEAD^
 213     git stash pop
 214
 215 (only do this if you pushed the
 216 previous change upstream,
 217 otherwise it is difficult to get
 218 the old changes back!) and repeat
 219 until each independent change is
 220 in its own commit. If you skip
 221 the ``git reset --hard`` step, you
 222 can also prepare a local feature
 223 branch from your changes.
 224
 225 .. rubric:: Q: How do I edit an earlier commit?
 226
 227 A: If you want to edit the latest
 228 commit, you can simply do the
 229 changes and use
 230
 231 ::
 232
 233     git commit --amend
 234
 235 If you want to edit some other
 236 commit, and commits after that
 237 have not changed the same lines,
 238 you can do the changes as usual
 239 and use
 240
 241 ::
 242
 243     git commit --fixup <commit>
 244
 245 or
 246
 247 ::
 248
 249     git commit --squash <commit>
 250
 251 where <commit> is the commit you
 252 want to change (the difference is
 253 that ``--fixup`` keeps the original
 254 commit message, while ``--squash``
 255 allows you to input additional
 256 notes and then edit the original
 257 commit message during ``git rebase
 258 -i``). You can do multiple commits
 259 in this way. You can also mix
 260 ``--fixup/--squash`` commits with
 261 normal commits. When you are
 262 done, use
 263
 264 ::
 265
 266     git rebase -i --autosquash <base-branch>
 267
 268 to merge the ``--fixup/--squash``
 269 commits to the commits they
 270 amend. See separate question on
 271 ``git rebase -i`` on how to choose
 272 <base-branch>.
 273
 274 In this kind of workflow, you
 275 should try to avoid to change the
 276 same lines in multiple commits
 277 (except in ``--fixup/--squash``
 278 commits), but if you have already
 279 changed some lines and want to
 280 edit an earlier commit, you can
 281 use
 282
 283 ::
 284
 285     git rebase -i <base-branch>
 286
 287 but you likely need to resolve
 288 some conflicts later. See ``git
 289 rebase -i`` question later.
 290
 291 .. rubric:: Q: How do I split a commit?
 292
 293 A: The instructions below apply
 294 to splitting the HEAD commit; see
 295 above how to use ``git rebase -i`` to
 296 get an earlier commit as HEAD to
 297 split it.
 298
 299 The simplest case is if you want
 300 to split a commit A into a chain
 301 A'-B-C, where A' is the first new
 302 commit, and contains most of the
 303 original commit, including the
 304 commit message. Then you can do
 305
 306 ::
 307
 308     git reset -p HEAD^ [-- <paths>]
 309     git commit --amend
 310
 311 to selectively remove parts from
 312 commit A, but leave them in your
 313 working tree. Then you can create
 314 one or more commits of the
 315 remaining changes as described in
 316 other tips.
 317
 318 If you want to split a commit A
 319 into a chain where the original
 320 commit message is reused for
 321 something else than the first
 322 commit (e.g., B-A'-C), then you
 323 can do
 324
 325 ::
 326
 327     git reset HEAD^
 328
 329 to remove the HEAD commit, but
 330 leave everything in your working
 331 tree. Then you can create your
 332 commits as described in other
 333 tips. When you come to a point
 334 where you want to reuse the
 335 original commit message, you can
 336 use
 337
 338 ::
 339
 340     git reflog
 341
 342 to find how to refer to your
 343 original commit as ``HEAD@{n}``, and
 344 then do
 345
 346 ::
 347
 348     git commit -c HEAD@{n}
 349
 350 .. rubric:: Q: How do I use git rebase -i to only edit local commits?
 351
 352 A: Assume that you have a local
 353 feature branch checked out, this
 354 branch has three commits, and
 355 that it is based on master.
 356 Further, assume that master has
 357 gotten a few more commits after
 358 you branched off. If you want to
 359 use ``git rebase -i`` to edit your
 360 feature branch (see above), you
 361 probably want to do
 362
 363 ::
 364
 365     git rebase -i HEAD~3
 366
 367 followed by a separate
 368
 369 ::
 370
 371     git rebase master
 372
 373 The first command allows you to
 374 edit your local branch without
 375 getting conflicts from changes in
 376 master. The latter allows you to
 377 resolve those conflicts in a
 378 separate rebase run. If you feel
 379 brave enough, you can also do
 380 both at the same time using
 381
 382 ::
 383
 384     git rebase -i master