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::
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 `Labels <https://docs.gitlab.com/ee/user/project/labels.html>`__
91 help developers by allowing additional filtering of issues and merge requests.
93 The GROMACS project `defines many labels <https://gitlab.com/gromacs/gromacs/-/labels>`__.
95 .. Note: labeling guidelines TBD. See https://gitlab.com/gromacs/gromacs/-/issues/3949 and open new issues as appropriate.
97 To minimize duplicated documentation, refer to the
98 `GROMACS Labels <https://gitlab.com/gromacs/gromacs/-/labels>`__ web interface for label descriptions.
100 When creating a new label, please provide a short description
101 so that people can understand what the label is intended to convey,
102 and when they should apply it to their own issues or merge requests.
106 * Ongoing categorizations to help specify the GROMACS component or development area use the ``#7F8C8D`` color.
107 * Specific features or subproject areas targeting an upcoming release use the ``#8E44AD`` background color.
108 * Status labels use ``#428BCA``. Note that Status labels are also used for Issues,
109 and are used according to
110 :ref:`status label guidelines <status label guidelines>`
112 .. Best practices and labeling policies can be proposed as changes to this document. See https://gitlab.com/gromacs/gromacs/-/issues/3949
117 Reviewing someone else's uploaded code
118 --------------------------------------
120 The reviewing workflow is the following:
122 #. https://gitlab.com/gromacs/gromacs/-/merge_requests shows all open changes
123 #. A change needs two approvals to go in, of which one approval has to come from
124 a member of either GMX Core or GMX Developers.
125 #. Usually a patch goes through several cycles of voting, commenting and
126 updating before it becomes merged, with votes from the developers indicating
127 if they think that change hat progressed enough to be included.
128 #. A change is submitted for merging and post-submit testing
131 Do not review your own code. The point of the policy is that at least
132 two non-authors have approved, and that the issues are resolved in the
133 opinion of the person who applies an approval before a merge. If you have
134 uploaded a minor fix to someone else's patch, use your judgement in
135 whether to approve yourself.
140 - First and foremost, check correctness to the extent possible;
141 - As portability and performance are the next most important things do check
142 for potential issues;
143 - Check adherence to the :ref:`GROMACS coding standards <style-guidelines>`;
144 - We should try to ensure that commits that implement bugfixes (as
145 well as important features and tasks) get an `issue tracker`_ entry created
146 and linked. The linking is done **automatically** through
147 `special syntax <https://gitlab.com/help/user/markdown#special-gitlab-references>`__
148 - If the commit is a **bugfix**\ :
150 - if present in the `issue tracker`_, it has to contain a valid reference to the
152 - if it's a **major bug**, there has to be a bug report filed in the
153 `issue tracker`_ (with urgent or
154 immediate priority) and referenced appropriately.
156 - If the commit is a **feature/task** implementation:
158 - if it's present in the `issue tracker`_ it
159 has to contain a valid reference to the issue;
160 - If no current issue is currently present and the change
161 would benefit of one for future explanation on why it was
162 added, a new issue should be created.
164 .. _status label guidelines:
166 Update the Status label
167 """""""""""""""""""""""
169 - Please update the Status label :ref:`for the issue <issue workflow>` when a merge request is under review.
170 - Please update the Status label :ref:`for the merge request <merge request status>` when it is closed.
172 .. _merge request status:
174 Closing Merge Requests
175 ----------------------
177 A merge request that has had no updates for six months or more can acquire the status label "Status::Stale"
178 If the proposed change still seems important and the next steps are unclear,
179 contributors with stale issues *are encouraged...*
181 - to contact existing reviewers (or potential reviewers),
182 - to participate in the developer mailing list, and
183 - to attend the biweekly teleconference to coordinate.
185 If the future of the merge request has not become clear within a month
186 (especially if it has become stale multiple times),
187 developers may close the merge request with a label indicating why it has entered a "closed" state.
188 `"Status::MR::..." labels <https://gitlab.com/gromacs/gromacs/-/labels?subscribed=&search=status%3A%3Amr>`__
189 do not indicate that the merge request has been reviewed
190 unless it is explicitly rejected.
192 See :issue:`4126` for background discussion.
194 - `Status::MR::Inactive <https://gitlab.com/gromacs/gromacs/-/merge_requests?label_name%5B%5D=Status%3A%3AMR%3A%3AInactive>`__: No response from contributor or no reviewers available for over six months.
195 - `Status::MR::Superseded <https://gitlab.com/gromacs/gromacs/-/merge_requests?label_name%5B%5D=Status%3A%3AMR%3A%3ASuperseded>`__: This merge request is no longer necessary.
196 - `Status::MR::Rejected <https://gitlab.com/gromacs/gromacs/-/merge_requests?label_name%5B%5D=Status%3A%3AMR%3A%3ARejected>`__: The solution (or its associated issue) will not be accepted.
197 - `Status::MR::Needs discussion <https://gitlab.com/gromacs/gromacs/-/merge_requests?label_name%5B%5D=Status%3A%3AMR%3A%3ANeeds+discussion>`__: More discussion must take place at the tracked issue before a MR is opened.
198 - `Status::Stale <https://gitlab.com/gromacs/gromacs/-/labels?subscribed=&search=status%3A%3AStale>`__: No activity for over six months.
200 .. seealso:: :ref:`issue workflow` for use of Status labels in Issue management.
205 .. rubric:: Q: Are there some other useful git configuration settings?
207 A: If you need to work with
208 branches that have large
209 differences (in particular, if a
210 lot of files have moved), it can
215 git config diff.renamelimit 5000
217 to increase the limit of inexact
218 renames that Git considers. The
219 default value is not sufficient,
220 for example, if you need to do a
221 merge or a cherry-pick from
222 a release branch to master.
224 .. rubric:: Q: How do I use git rebase (also ``git pull --rebase``)?
226 A: Assume you have a local
227 feature branch checked out, that
228 it is based on master, and master
229 has gotten new commits. You can
236 to move your commits on top of
237 the newest commit in master. This
238 will save each commit you did,
239 and replay them on top of master.
240 If any commit results in
241 conflicts, you need to resolve
242 them as usual (including marking
243 them as resolved using git add),
248 git rebase --continue
250 Note that unless you are sure
251 about what you are doing, you
252 should not use any commands that
253 create or delete commits (git
254 commit, or git checkout or git
255 reset without paths). ``git rebase
256 --continue`` will create the commit
257 after conflicts have been
258 resolved, with the original
259 commit message (you will get a
262 If you realize that the conflicts
263 are too messy to resolve (or that
264 you made a mistake that resulted
265 in messy conflicts), you can use
271 to get back into the state you
272 started from (before the
273 original git rebase master
274 invocation). If the rebase is
275 already finished, and you realize
276 you made a mistake, you can get
277 back where you started with
279 log <my-branch>@{1} and/or git
280 reflog <my-branch> to check that
281 this is where you want to go)
285 git reset --hard <my-branch>@{1}
287 .. rubric:: Q: How do I prepare several commits at once?
289 A: Assume I have multiple independent changes in my working tree.
296 to add one independent change at
297 a time to the index. Use
303 to check that the index contains
304 the changes you want. You can
305 then commit this one change:
311 If you want to test that the
312 change works, use to temporarily
313 store away other changes, and do
320 If the testing fails, you can
321 amend your existing commit with
322 ``git commit --amend``. After you are
323 satisfied, you can push the
324 commit for review. If
325 you stashed away your changes and
326 you want the next change to be
327 reviewed independently, do
331 git reset --hard HEAD^
334 (only do this if you pushed the
335 previous change upstream,
336 otherwise it is difficult to get
337 the old changes back!) and repeat
338 until each independent change is
339 in its own commit. If you skip
340 the ``git reset --hard`` step, you
341 can also prepare a local feature
342 branch from your changes.
344 .. rubric:: Q: How do I edit an earlier commit?
346 A: If you want to edit the latest
347 commit, you can simply do the
354 If you want to edit some other
355 commit, and commits after that
356 have not changed the same lines,
357 you can do the changes as usual
362 git commit --fixup <commit>
368 git commit --squash <commit>
370 where <commit> is the commit you
371 want to change (the difference is
372 that ``--fixup`` keeps the original
373 commit message, while ``--squash``
374 allows you to input additional
375 notes and then edit the original
376 commit message during ``git rebase
377 -i``). You can do multiple commits
378 in this way. You can also mix
379 ``--fixup/--squash`` commits with
380 normal commits. When you are
385 git rebase -i --autosquash <base-branch>
387 to merge the ``--fixup/--squash``
388 commits to the commits they
389 amend. See separate question on
390 ``git rebase -i`` on how to choose
393 In this kind of workflow, you
394 should try to avoid to change the
395 same lines in multiple commits
396 (except in ``--fixup/--squash``
397 commits), but if you have already
398 changed some lines and want to
399 edit an earlier commit, you can
404 git rebase -i <base-branch>
406 but you likely need to resolve
407 some conflicts later. See ``git
408 rebase -i`` question later.
410 .. rubric:: Q: How do I split a commit?
412 A: The instructions below apply
413 to splitting the HEAD commit; see
414 above how to use ``git rebase -i`` to
415 get an earlier commit as HEAD to
418 The simplest case is if you want
419 to split a commit A into a chain
420 A'-B-C, where A' is the first new
421 commit, and contains most of the
422 original commit, including the
423 commit message. Then you can do
427 git reset -p HEAD^ [-- <paths>]
430 to selectively remove parts from
431 commit A, but leave them in your
432 working tree. Then you can create
433 one or more commits of the
434 remaining changes as described in
437 If you want to split a commit A
438 into a chain where the original
439 commit message is reused for
440 something else than the first
441 commit (e.g., B-A'-C), then you
448 to remove the HEAD commit, but
449 leave everything in your working
450 tree. Then you can create your
451 commits as described in other
452 tips. When you come to a point
453 where you want to reuse the
454 original commit message, you can
461 to find how to refer to your
462 original commit as ``HEAD@{n}``, and
467 git commit -c HEAD@{n}
469 .. rubric:: Q: How do I use git rebase -i to only edit local commits?
471 A: Assume that you have a local
472 feature branch checked out, this
473 branch has three commits, and
474 that it is based on master.
475 Further, assume that master has
476 gotten a few more commits after
477 you branched off. If you want to
478 use ``git rebase -i`` to edit your
479 feature branch (see above), you
486 followed by a separate
492 The first command allows you to
493 edit your local branch without
494 getting conflicts from changes in
495 master. The latter allows you to
496 resolve those conflicts in a
497 separate rebase run. If you feel
498 brave enough, you can also do
499 both at the same time using