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.
30 See `gmx-codeformatting` for help meeting and testing the style guidelines.
32 Setting up login credentials with gitlab
33 ----------------------------------------
35 You will need a public ssh key. If you were using Gerrit, you probably
36 already have one and you can ignore the first line::
38 ssh-keygen -t rsa -C "your.email@address.com"
41 Copy the output of the last command, got to gitlab.com, find you user in the
42 right top corner and select settings.
44 Chose SSH keys in the menu on the left and past your key in the text field.
49 The meta-level code design and discussions is organised in issues and visible at
50 https://gitlab.com/gromacs/gromacs/-/issues. Please check if if your issue or a
51 similar issue already exists before creating a new one.
53 Note that all Redmine issues have been transferred to gitlab with the same issue
54 numbers as used in gitlab. However, comments and discussion are now represented
55 by gitlab user @acmnpv - the original authors are found inline at the bottom of
58 Uploading code for review - creating a merge request
59 ----------------------------------------------------
61 Issues are addressed with new code via "merge requests" (MR). Find the current
62 MRs at https://gitlab.com/gromacs/gromacs/-/merge_requests.
63 There are two ways of creating a merge request - either via the gitlab graphical
64 user interface or via the command line.
66 To use the GUI, find the relevant issue or open a new one, then find the
67 "create merge request" button to create a merge request related to that issue in gitlab.
68 The default selection is to mark this a work in progress (WIP) merge-request.
69 We recommend keeping this setting until you are completely satisfied with the
70 code yourself and all tests are passed.
72 Select milestone and assignees to make tracking of the progress easier.
73 Keep the requirements for merging as they are set by default.
75 You can also use ``git push`` on the command line directly and create a merge request
76 following the link that is output on the command line.
78 Your repository should be in sync with the GROMACS repository. To ensure this,
79 use ``git fetch`` to obtain the newest branches, then merge the master branch
80 into your branch with ``git merge master`` while on your branch.
85 Good names: documentation_UpdateDevelopersDocsTOGitLab, nbnxm_MakeNbnxmGPUIntoClass, pme_FEPPMEGPU.
86 Bad names: branch1234, mybranch, test, etc
91 `Labels <https://docs.gitlab.com/ee/user/project/labels.html>`__
92 help developers by allowing additional filtering of issues and merge requests.
94 The GROMACS project `defines many labels <https://gitlab.com/gromacs/gromacs/-/labels>`__.
96 .. Note: labeling guidelines TBD. See https://gitlab.com/gromacs/gromacs/-/issues/3949 and open new issues as appropriate.
100 * Ongoing categorizations to help specify the GROMACS component or development area use the ``#7F8C8D`` color.
101 * Specific features or subproject areas targeting an upcoming release use the ``#8E44AD`` background color.
103 When creating a new label, please provide a short description
104 so that people can understand what the label is intended to convey,
105 and when they should apply it to their own issues or merge requests.
107 .. Best practices and labeling policies can be proposed as changes to this document. See https://gitlab.com/gromacs/gromacs/-/issues/3949
112 Reviewing someone else's uploaded code
113 --------------------------------------
115 The reviewing workflow is the following:
117 #. https://gitlab.com/gromacs/gromacs/-/merge_requests shows all open changes
118 #. A change needs two approvals to go in, of which one approval has to come from
119 a member of either GMX Core or GMX Developers.
120 #. Usually a patch goes through several cycles of voting, commenting and
121 updating before it becomes merged, with votes from the developers indicating
122 if they think that change hat progressed enough to be included.
123 #. A change is submitted for merging and post-submit testing
126 Do not review your own code. The point of the policy is that at least
127 two non-authors have approved, and that the issues are resolved in the
128 opinion of the person who applies an approval before a merge. If you have
129 uploaded a minor fix to someone else's patch, use your judgement in
130 whether to approve yourself.
135 - First and foremost, check correctness to the extent possible;
136 - As portability and performance are the next most important things do check
137 for potential issues;
138 - Check adherence to the :ref:`GROMACS coding standards <style-guidelines>`;
139 - We should try to ensure that commits that implement bugfixes (as
140 well as important features and tasks) get an `issue tracker`_ entry created
141 and linked. The linking is done **automatically** through
142 `special syntax <https://gitlab.com/help/user/markdown#special-gitlab-references>`__
143 - If the commit is a **bugfix**\ :
145 - if present in the `issue tracker`_, it has to contain a valid reference to the
147 - if it's a **major bug**, there has to be a bug report filed in the
148 `issue tracker`_ (with urgent or
149 immediate priority) and referenced appropriately.
151 - If the commit is a **feature/task** implementation:
153 - if it's present in the `issue tracker`_ it
154 has to contain a valid reference to the issue;
155 - If no current issue is currently present and the change
156 would benefit of one for future explanation on why it was
157 added, a new issue should be created.
159 Moving code from gerrit to gitlab
160 =================================
162 Create a local repository that is connected to both Gerrit and Gitlab::
164 git clone git@gitlab.com:gromacs/gromacs.git -o gitlab gromacs-migrate
166 git remote add gerrit ssh://<gerrit-username>@gerrit.gromacs.org/gromacs.git
169 Checkout the current gitlab master::
171 git checkout gitlab/master
173 Go to your commit on https://gerrit.gromacs.org/ , select Download->Cherry-Pick
175 ``git fetch "https://gerrit.gromacs.org/gromacs" refs/changes/XX/YYYY/ZZ && git cherry-pick FETCH_HEAD``
177 Resolve conflicts, if any. If you need to do further changes to your patch,
178 feel free to ammend them at this point. Remove the Gerrit commit-id line from
179 the bottom of the commit message, but keep the issue (ex. redmine) references -
180 they match the gitlab issues.
182 Do not forget to run clang-format script (``admin/clang-format.sh update -f --rev=HEAD^``)
183 and copyright script (``admin/copyright.sh update -f --rev=HEAD^``).
185 When ready, move the patch to a new branch::
187 git branch <branch-name>
189 Make sure to select a unique branch name that it is easy for you to connect to
190 a specific patch. You will need it later to make changes to your merge request.
191 Keep in mind that your branch name is going to be exposed to everyone while
192 your patch is under review. Push the branch to GitLab::
194 git push gitlab <branch-name>
196 Go to https://gitlab.com/gromacs/gromacs and create a merge request.
197 Copy-paste your commit message from Gerrit into the merge request description
198 text box, use the first line as a title. If your branch has only one commit,
199 this will be done automatically. Add "From: https://gerrit.gromacs.org/#/c/gromacs/+/XXXXX/"
200 to the end of your commit message.
201 Select "Delete source branch when merge request is accepted." check-box.
202 Select "Squash commits when merge request is accepted" check-box.
203 Check and that squash commit message is correct. If necessary, update it.
205 If your change in Gerrit depends on another Gerrit change:
207 Make sure that you transfer the parent change to GitLab first.
208 When transferring the child change, specify the parent in the "Merge request dependencies" text field.
209 In GitLab menu, go to Repository -> Compare. Select the branch that correspond
210 to the child change as a Source in the drop-down menu, choose parent change as
211 the Target. Click Compare button and copy the link from the browser address bar.
212 Add "Compare to the parent: https://gitlab.com/gromacs/gromacs/-/compare/PARENT_BRANCH...CHILD_BRANCH"
213 to the description of the merge request. You will have to keep this dependency
214 up to date for the link to work properly. For example, if you update the parent,
215 you will need to merge its branch to the child branch right away.
216 Otherwise your recent updates will show up in comparison.
222 .. rubric:: Q: Are there some other useful git configuration settings?
224 A: If you need to work with
225 branches that have large
226 differences (in particular, if a
227 lot of files have moved), it can
232 git config diff.renamelimit 5000
234 to increase the limit of inexact
235 renames that Git considers. The
236 default value is not sufficient,
237 for example, if you need to do a
238 merge or a cherry-pick from
239 a release branch to master.
241 .. rubric:: Q: How do I use git rebase (also ``git pull --rebase``)?
243 A: Assume you have a local
244 feature branch checked out, that
245 it is based on master, and master
246 has gotten new commits. You can
253 to move your commits on top of
254 the newest commit in master. This
255 will save each commit you did,
256 and replay them on top of master.
257 If any commit results in
258 conflicts, you need to resolve
259 them as usual (including marking
260 them as resolved using git add),
265 git rebase --continue
267 Note that unless you are sure
268 about what you are doing, you
269 should not use any commands that
270 create or delete commits (git
271 commit, or git checkout or git
272 reset without paths). ``git rebase
273 --continue`` will create the commit
274 after conflicts have been
275 resolved, with the original
276 commit message (you will get a
279 If you realize that the conflicts
280 are too messy to resolve (or that
281 you made a mistake that resulted
282 in messy conflicts), you can use
288 to get back into the state you
289 started from (before the
290 original git rebase master
291 invocation). If the rebase is
292 already finished, and you realize
293 you made a mistake, you can get
294 back where you started with
296 log <my-branch>@{1} and/or git
297 reflog <my-branch> to check that
298 this is where you want to go)
302 git reset --hard <my-branch>@{1}
304 .. rubric:: Q: How do I prepare several commits at once?
306 A: Assume I have multiple independent changes in my working tree.
313 to add one independent change at
314 a time to the index. Use
320 to check that the index contains
321 the changes you want. You can
322 then commit this one change:
328 If you want to test that the
329 change works, use to temporarily
330 store away other changes, and do
337 If the testing fails, you can
338 amend your existing commit with
339 ``git commit --amend``. After you are
340 satisfied, you can push the
341 commit for review. If
342 you stashed away your changes and
343 you want the next change to be
344 reviewed independently, do
348 git reset --hard HEAD^
351 (only do this if you pushed the
352 previous change upstream,
353 otherwise it is difficult to get
354 the old changes back!) and repeat
355 until each independent change is
356 in its own commit. If you skip
357 the ``git reset --hard`` step, you
358 can also prepare a local feature
359 branch from your changes.
361 .. rubric:: Q: How do I edit an earlier commit?
363 A: If you want to edit the latest
364 commit, you can simply do the
371 If you want to edit some other
372 commit, and commits after that
373 have not changed the same lines,
374 you can do the changes as usual
379 git commit --fixup <commit>
385 git commit --squash <commit>
387 where <commit> is the commit you
388 want to change (the difference is
389 that ``--fixup`` keeps the original
390 commit message, while ``--squash``
391 allows you to input additional
392 notes and then edit the original
393 commit message during ``git rebase
394 -i``). You can do multiple commits
395 in this way. You can also mix
396 ``--fixup/--squash`` commits with
397 normal commits. When you are
402 git rebase -i --autosquash <base-branch>
404 to merge the ``--fixup/--squash``
405 commits to the commits they
406 amend. See separate question on
407 ``git rebase -i`` on how to choose
410 In this kind of workflow, you
411 should try to avoid to change the
412 same lines in multiple commits
413 (except in ``--fixup/--squash``
414 commits), but if you have already
415 changed some lines and want to
416 edit an earlier commit, you can
421 git rebase -i <base-branch>
423 but you likely need to resolve
424 some conflicts later. See ``git
425 rebase -i`` question later.
427 .. rubric:: Q: How do I split a commit?
429 A: The instructions below apply
430 to splitting the HEAD commit; see
431 above how to use ``git rebase -i`` to
432 get an earlier commit as HEAD to
435 The simplest case is if you want
436 to split a commit A into a chain
437 A'-B-C, where A' is the first new
438 commit, and contains most of the
439 original commit, including the
440 commit message. Then you can do
444 git reset -p HEAD^ [-- <paths>]
447 to selectively remove parts from
448 commit A, but leave them in your
449 working tree. Then you can create
450 one or more commits of the
451 remaining changes as described in
454 If you want to split a commit A
455 into a chain where the original
456 commit message is reused for
457 something else than the first
458 commit (e.g., B-A'-C), then you
465 to remove the HEAD commit, but
466 leave everything in your working
467 tree. Then you can create your
468 commits as described in other
469 tips. When you come to a point
470 where you want to reuse the
471 original commit message, you can
478 to find how to refer to your
479 original commit as ``HEAD@{n}``, and
484 git commit -c HEAD@{n}
486 .. rubric:: Q: How do I use git rebase -i to only edit local commits?
488 A: Assume that you have a local
489 feature branch checked out, this
490 branch has three commits, and
491 that it is based on master.
492 Further, assume that master has
493 gotten a few more commits after
494 you branched off. If you want to
495 use ``git rebase -i`` to edit your
496 feature branch (see above), you
503 followed by a separate
509 The first command allows you to
510 edit your local branch without
511 getting conflicts from changes in
512 master. The latter allows you to
513 resolve those conflicts in a
514 separate rebase run. If you feel
515 brave enough, you can also do
516 both at the same time using