5 This documentation assumes the reader is already familiary with using ``git``
6 for managing file revisions.
14 GROMACS development happens on gitlab at https://gitlab.com/gromacs/gromacs.
15 Create a user account at https://gitlab.com/users/sign_in#register-pane or use
16 an exisiting account at gitlab.com. For more information on how to use gitlab have
17 a look at their extensive user documentation at https://docs.gitlab.com/ee/user/index.html.
18 We follow the workflow described in https://docs.gitlab.com/ee/topics/gitlab_flow.html.
20 If you do not already have a GROMACS repository set up, user
21 ``git clone git@gitlab.com:gromacs/gromacs.git`` to obtain the current GROMACS
22 repository from gitlab. Otherwise use
23 ``git remote add gitlab git@gitlab.com:gromacs/gromacs.git``.
25 Using gitlab, new code enters GROMACS by merging git development branches into
28 To automatically detect issues in new code, it is tested within continuous
29 integration (CI) with a large combination of settings.
31 Setting up login credentials with gitlab
32 ----------------------------------------
34 You will need a public ssh key. If you were using Gerrit, you probably
35 already have one and you can ignore the first line::
37 ssh-keygen -t rsa -C "your.email@address.com"
40 Copy the output of the last command, got to gitlab.com, find you user in the
41 right top corner and select settings.
43 Chose SSH keys in the menu on the left and past your key in the text field.
48 The meta-level code design and discussions is organised in issues and visible at
49 https://gitlab.com/gromacs/gromacs/-/issues. Please check if if your issue or a
50 similar issue already exists before creating a new one.
52 Note that all Redmine issues have been transferred to gitlab with the same issue
53 numbers as used in gitlab. However, comments and discussion are now represented
54 by gitlab user @acmnpv - the original authors are found inline at the bottom of
57 Uploading code for review - creating a merge request
58 ----------------------------------------------------
60 Issues are addressed with new code via "merge requests" (MR). Find the current
61 MRs at https://gitlab.com/gromacs/gromacs/-/merge_requests.
62 There are two ways of creating a merge request - either via the gitlab graphical
63 user interface or via the command line.
65 To use the GUI, find the relevant issue or open a new one, then find the
66 "create merge request" button to create a merge request related to that issue in gitlab.
67 The default selection is to mark this a work in progress (WIP) merge-request.
68 We recommend keeping this setting until you are completely satisfied with the
69 code yourself and all tests are passed.
71 Select milestone and assignees to make tracking of the progress easier.
72 Keep the requirements for merging as they are set by default.
74 You can also use ``git push`` on the command line directly and create a merge request
75 following the link that is output on the command line.
77 Your repository should be in sync with the GROMACS repository. To ensure this,
78 use ``git fetch`` to obtain the newest branches, then merge the master branch
79 into your branch with ``git merge master`` while on your branch.
84 Good names: documentation_UpdateDevelopersDocsTOGitLab, nbnxm_MakeNbnxmGPUIntoClass, pme_FEPPMEGPU.
85 Bad names: branch1234, mybranch, test, etc
90 Reviewing someone else's uploaded code
91 --------------------------------------
93 The reviewing workflow is the following:
95 #. https://gitlab.com/gromacs/gromacs/-/issues shows all open changes
96 #. A change needs two approvals to go in, of which one approval has to come from
97 a member of either GMX Core or GMX Developers.
98 #. Usually a patch goes through several cycles of voting, commenting and
99 updating before it becomes merged, with votes from the developers indicating
100 if they think that change hat progressed enough to be included.
101 #. A change is submitted for merging and post-submit testing
104 Do not review your own code. The point of the policy is that at least
105 two non-authors have approved, and that the issues are resolved in the
106 opinion of the person who applies an approval before a merge. If you have
107 uploaded a minor fix to someone else's patch, use your judgement in
108 whether to approve yourself.
113 - First and foremost, check correctness to the extent possible;
114 - As portability and performance are the next most important things do check
115 for potential issues;
116 - Check adherence to the :ref:`GROMACS coding standards <style-guidelines>`;
117 - We should try to ensure that commits that implement bugfixes (as
118 well as important features and tasks) get an `issue tracker`_ entry created
119 and linked. The linking is done **automatically** through
120 `special syntax <https://gitlab.com/help/user/markdown#special-gitlab-references>`__
121 - If the commit is a **bugfix**\ :
123 - if present in the `issue tracker`_, it has to contain a valid reference to the
125 - if it's a **major bug**, there has to be a bug report filed in the
126 `issue tracker`_ (with urgent or
127 immediate priority) and referenced appropriately.
129 - If the commit is a **feature/task** implementation:
131 - if it's present in the `issue tracker`_ it
132 has to contain a valid reference to the issue;
133 - If no current issue is currently present and the change
134 would benefit of one for future explanation on why it was
135 added, a new issue should be created.
137 Moving code from gerrit to gitlab
138 =================================
140 Create a local repository that is connected to both Gerrit and Gitlab::
142 git clone git@gitlab.com:gromacs/gromacs.git -o gitlab gromacs-migrate
144 git remote add gerrit ssh://<gerrit-username>@gerrit.gromacs.org/gromacs.git
147 Checkout the current gitlab master::
149 git checkout gitlab/master
151 Go to your commit on https://gerrit.gromacs.org/ , select Download->Cherry-Pick
153 ``git fetch "https://gerrit.gromacs.org/gromacs" refs/changes/XX/YYYY/ZZ && git cherry-pick FETCH_HEAD``
155 Resolve conflicts, if any. If you need to do further changes to your patch,
156 feel free to ammend them at this point. Remove the Gerrit commit-id line from
157 the bottom of the commit message, but keep the issue (ex. redmine) references -
158 they match the gitlab issues.
160 Do not forget to run clang-format script (``admin/clang-format.sh update -f --rev=HEAD^``)
161 and copyright script (``admin/copyright.sh update -f --rev=HEAD^``).
163 When ready, move the patch to a new branch::
165 git branch <branch-name>
167 Make sure to select a unique branch name that it is easy for you to connect to
168 a specific patch. You will need it later to make changes to your merge request.
169 Keep in mind that your branch name is going to be exposed to everyone while
170 your patch is under review. Push the branch to GitLab::
172 git push gitlab <branch-name>
174 Go to https://gitlab.com/gromacs/gromacs and create a merge request.
175 Copy-paste your commit message from Gerrit into the merge request description
176 text box, use the first line as a title. If your branch has only one commit,
177 this will be done automatically. Add "From: https://gerrit.gromacs.org/#/c/gromacs/+/XXXXX/"
178 to the end of your commit message.
179 Select "Delete source branch when merge request is accepted." check-box.
180 Select "Squash commits when merge request is accepted" check-box.
181 Check and that squash commit message is correct. If necessary, update it.
183 If your change in Gerrit depends on another Gerrit change:
185 Make sure that you transfer the parent change to GitLab first.
186 When transferring the child change, specify the parent in the "Merge request dependencies" text field.
187 In GitLab menu, go to Repository -> Compare. Select the branch that correspond
188 to the child change as a Source in the drop-down menu, choose parent change as
189 the Target. Click Compare button and copy the link from the browser address bar.
190 Add "Compare to the parent: https://gitlab.com/gromacs/gromacs/-/compare/PARENT_BRANCH...CHILD_BRANCH"
191 to the description of the merge request. You will have to keep this dependency
192 up to date for the link to work properly. For example, if you update the parent,
193 you will need to merge its branch to the child branch right away.
194 Otherwise your recent updates will show up in comparison.
200 .. rubric:: Q: Are there some other useful git configuration settings?
202 A: If you need to work with
203 branches that have large
204 differences (in particular, if a
205 lot of files have moved), it can
210 git config diff.renamelimit 5000
212 to increase the limit of inexact
213 renames that Git considers. The
214 default value is not sufficient,
215 for example, if you need to do a
216 merge or a cherry-pick from
217 a release branch to master.
219 .. rubric:: Q: How do I use git rebase (also ``git pull --rebase``)?
221 A: Assume you have a local
222 feature branch checked out, that
223 it is based on master, and master
224 has gotten new commits. You can
231 to move your commits on top of
232 the newest commit in master. This
233 will save each commit you did,
234 and replay them on top of master.
235 If any commit results in
236 conflicts, you need to resolve
237 them as usual (including marking
238 them as resolved using git add),
243 git rebase --continue
245 Note that unless you are sure
246 about what you are doing, you
247 should not use any commands that
248 create or delete commits (git
249 commit, or git checkout or git
250 reset without paths). ``git rebase
251 --continue`` will create the commit
252 after conflicts have been
253 resolved, with the original
254 commit message (you will get a
257 If you realize that the conflicts
258 are too messy to resolve (or that
259 you made a mistake that resulted
260 in messy conflicts), you can use
266 to get back into the state you
267 started from (before the
268 original git rebase master
269 invocation). If the rebase is
270 already finished, and you realize
271 you made a mistake, you can get
272 back where you started with
274 log <my-branch>@{1} and/or git
275 reflog <my-branch> to check that
276 this is where you want to go)
280 git reset --hard <my-branch>@{1}
282 .. rubric:: Q: How do I prepare several commits at once?
284 A: Assume I have multiple independent changes in my working tree.
291 to add one independent change at
292 a time to the index. Use
298 to check that the index contains
299 the changes you want. You can
300 then commit this one change:
306 If you want to test that the
307 change works, use to temporarily
308 store away other changes, and do
315 If the testing fails, you can
316 amend your existing commit with
317 ``git commit --amend``. After you are
318 satisfied, you can push the
319 commit for review. If
320 you stashed away your changes and
321 you want the next change to be
322 reviewed independently, do
326 git reset --hard HEAD^
329 (only do this if you pushed the
330 previous change upstream,
331 otherwise it is difficult to get
332 the old changes back!) and repeat
333 until each independent change is
334 in its own commit. If you skip
335 the ``git reset --hard`` step, you
336 can also prepare a local feature
337 branch from your changes.
339 .. rubric:: Q: How do I edit an earlier commit?
341 A: If you want to edit the latest
342 commit, you can simply do the
349 If you want to edit some other
350 commit, and commits after that
351 have not changed the same lines,
352 you can do the changes as usual
357 git commit --fixup <commit>
363 git commit --squash <commit>
365 where <commit> is the commit you
366 want to change (the difference is
367 that ``--fixup`` keeps the original
368 commit message, while ``--squash``
369 allows you to input additional
370 notes and then edit the original
371 commit message during ``git rebase
372 -i``). You can do multiple commits
373 in this way. You can also mix
374 ``--fixup/--squash`` commits with
375 normal commits. When you are
380 git rebase -i --autosquash <base-branch>
382 to merge the ``--fixup/--squash``
383 commits to the commits they
384 amend. See separate question on
385 ``git rebase -i`` on how to choose
388 In this kind of workflow, you
389 should try to avoid to change the
390 same lines in multiple commits
391 (except in ``--fixup/--squash``
392 commits), but if you have already
393 changed some lines and want to
394 edit an earlier commit, you can
399 git rebase -i <base-branch>
401 but you likely need to resolve
402 some conflicts later. See ``git
403 rebase -i`` question later.
405 .. rubric:: Q: How do I split a commit?
407 A: The instructions below apply
408 to splitting the HEAD commit; see
409 above how to use ``git rebase -i`` to
410 get an earlier commit as HEAD to
413 The simplest case is if you want
414 to split a commit A into a chain
415 A'-B-C, where A' is the first new
416 commit, and contains most of the
417 original commit, including the
418 commit message. Then you can do
422 git reset -p HEAD^ [-- <paths>]
425 to selectively remove parts from
426 commit A, but leave them in your
427 working tree. Then you can create
428 one or more commits of the
429 remaining changes as described in
432 If you want to split a commit A
433 into a chain where the original
434 commit message is reused for
435 something else than the first
436 commit (e.g., B-A'-C), then you
443 to remove the HEAD commit, but
444 leave everything in your working
445 tree. Then you can create your
446 commits as described in other
447 tips. When you come to a point
448 where you want to reuse the
449 original commit message, you can
456 to find how to refer to your
457 original commit as ``HEAD@{n}``, and
462 git commit -c HEAD@{n}
464 .. rubric:: Q: How do I use git rebase -i to only edit local commits?
466 A: Assume that you have a local
467 feature branch checked out, this
468 branch has three commits, and
469 that it is based on master.
470 Further, assume that master has
471 gotten a few more commits after
472 you branched off. If you want to
473 use ``git rebase -i`` to edit your
474 feature branch (see above), you
481 followed by a separate
487 The first command allows you to
488 edit your local branch without
489 getting conflicts from changes in
490 master. The latter allows you to
491 resolve those conflicts in a
492 separate rebase run. If you feel
493 brave enough, you can also do
494 both at the same time using