You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -9,7 +9,7 @@ The MITgcm is an open source project that relies on the participation of its use
9
9
Bugs and feature requests
10
10
=========================
11
11
12
-
If you think you've found a bug, the best thing to check that you're using the latest version of the model. If the bug is still in the latest version, then think about how you might fix it and file a ticket in the GitHub issue tracker [url to be inserted once we have the proper repo]. Please include as much detail as possible. At a minimum your ticket should include:
12
+
If you think you've found a bug, the first thing to check that you're using the latest version of the model. If the bug is still in the latest version, then think about how you might fix it and file a ticket in the `GitHub issue tracker <https://github.com/altMITgcm/MITgcm/issues>`_. Please include as much detail as possible. At a minimum your ticket should include:
13
13
14
14
- what the bug does;
15
15
- the location of the bug: file name and line number(s); and
@@ -22,44 +22,50 @@ To request a new feature, or guidance on how to implement it yourself, please op
22
22
23
23
24
24
25
-
Contributing to the code
25
+
Using Git and Github
26
26
========================
27
27
28
-
To contribute to the source code of the model you will need to fork the repository and place a pull request on GitHub. The two following sections describe this process in different levels of detail. If you are unfamiliar with git, you may wish to skip the quickstart guide and use the detailed instructions. All contributions are expected to conform with the :ref:`subsec_code_style_guide`.
28
+
To contribute to the source code of the model you will need to fork the repository and place a pull request on GitHub. The two following sections describe this process in different levels of detail. If you are unfamiliar with git, you may wish to skip the quickstart guide and use the detailed instructions. All contributions are expected to conform with the :ref:`sec_code_style_guide`.
29
29
30
30
31
31
Quickstart Guide
32
32
----------------
33
33
34
34
1. Fork the project on GitHub (using the fork button) and create a local clone, if you haven’t already:
3. This step is optional, but highly recommended. It will ensure that your GitHub repo stays up to date with the main repository. Checkout the master branch and sync everywhere:
43
47
44
-
|``git checkout master``
45
-
|``git pull upstream master``
46
-
|``git push origin master``
47
-
|
48
+
::
48
49
50
+
% git checkout master
51
+
% git pull upstream master
52
+
% git push origin master
53
+
54
+
4. Make a new branch from ``upstream/master`` (name it something appropriate, here we assume it is a bugfix) and make edits on this branch:
49
55
50
-
4. Make a new branch from `upstream/master` (name it something appropriate, here we assume it is a bugfix) and make edits on this branch:
56
+
::
51
57
52
-
|``git fetch upstream``
53
-
|``git checkout -b bugfix upstream/master``
54
-
|
58
+
% git fetch upstream
59
+
% git checkout -b bugfix upstream/master
55
60
56
61
5. When edits are done, do all git add’s and git commit’s. In the commit, make a succinct (<70 char) summary, followed by a blank line and a longer description. Reference any outstanding issues addressed using the syntax ``#ISSUE_NUMBER``.
57
62
58
-
|
59
63
60
64
6. Push the edited branch to the origin remote (i.e. your fork) on GitHub:
61
65
62
-
``git push -u origin bugfix``
66
+
::
67
+
68
+
% git push -u origin bugfix
63
69
64
70
7. On GitHub, go to your fork and hit the pull request (PR) button, and wait for the MITgcm head developers to review your proposed changes. You may get additional questions or requests before your changes are accepted into the primary MITgcm source code.
65
71
@@ -81,6 +87,15 @@ The most common git commands are:
81
87
82
88
What is GitHub then? GitHub is a website that has three major purposes: 1) Code Viewer: through your browser, you can view all source code and all changes to such over time; 2) “Pull Requests”: facilitates the process whereby code developers submit changes to the primary MITgcm maintainers; 3) the “Cloud”: GitHub functions as a cloud server to store different copies of the code. The utility of #1 is fairly obvious. For #2 and #3, without GitHub, one might envision making a big tarball of edited files and emailing the maintainers for inclusion in the main repository. Instead, GitHub effectively does something like this for you in a much more elegant way. Note unlike using (linux terminal command) git, GitHub commands are NOT typed in a terminal, but are typically invoked by hitting a button on the web interface, or clicking on a webpage link etc. To contribute edits to MITgcm, you need to obtain a github account. It’s free; do this first if you don’t have one already.
83
89
90
+
Before you start working with git, make sure you identify yourself. Type:
(note the required quotes around your name). You should also personalize your profile associated with your GitHub account.
98
+
84
99
There are many online tutorials to using Git and GitHub (see for example https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project ); here, we are just communicating the basics necessary to submit code changes to the MITgcm. Spending some time learning the more advanced features of Git will likely pay off in the long run, and not just for MITgcm contributions, as you are likely to encounter it in all sorts of different projects.
85
100
86
101
To better understand this process, :numref:`git_setup` shows a conceptual map of the Git setup. Note three copies of the code: the main MITgcm repository sourcecode “upstream” (i.e., owned by the MITgcm maintainers) in the GitHub cloud, a copy of the repository “origin” owned by you, also residing in the GitHub cloud, and a local copy on your personal computer or compute cluster (where you intend to compile and run). The Git and GitHub commands to create this setup are explained more fully below.
@@ -99,44 +114,63 @@ One other aspect of Git that requires some explanation to the uninitiated: your
99
114
100
115
A detailed explanation of steps for contributing MITgcm code edits:
101
116
102
-
1. On GitHub, create a local clone (copy) of the repository in your GitHub cloud user space. From the main repository (https://github.com/altMITgcm/MITgcm) hit the **Fork** button. You now need to download the code onto your local computer using the git clone command. If you previously downloaded the code through a tarball or some other means, you will need to obtain a new, local, git-aware version via
117
+
1. On GitHub, create a local clone (copy) of the repository in your GitHub cloud user space. From the main repository (https://github.com/altMITgcm/MITgcm) hit the **Fork** button. You now need to download the code onto your local computer using the git clone command. If you previously downloaded the code through a tarball or some other means, you will need to obtain a new, local, git-aware version via:
from your terminal (technically, here you are copying the forked “origin” version from the cloud, not the “upstream” version, but these will be identical at this point).
|from your terminal (technically, here you are copying the forked “origin” version from the cloud, not the “upstream” version, but these will be identical at this point).
124
+
|
107
125
108
126
2. Move into the local clone directory on your computer:
109
127
110
-
``cd MITgcm66h``
128
+
::
111
129
112
-
Finally, we need to set up a remote that points to the main repository:
|Finally, we need to set up a remote that points to the main repository:
133
+
|
134
+
135
+
::
115
136
116
-
This means that we now have two "remotes" of the project (a “remote” is just a pointer to a repository not on your computer, i.e. in the GitHub cloud), one pointing to your GitHub user space (“origin”), and this new remote pointing to the original (“upstream”). You can read and write into your "origin" version (since it belongs to you, in the cloud), but not into the "upstream" version. This command just sets up this remote, which is needed in step 3 -- no actual file manipulation is done.
|This means that we now have two "remotes" of the project (a “remote” is just a pointer to a repository not on your computer, i.e. in the GitHub cloud), one pointing to your GitHub user space (“origin”), and this new remote pointing to the original (“upstream”). You can read and write into your "origin" version (since it belongs to you, in the cloud), but not into the "upstream" version. This command just sets up this remote, which is needed in step 3 -- no actual file manipulation is done.
140
+
|
118
141
119
142
3. Switch to the master branch, and make sure we're up to date.
120
143
121
-
``git checkout master``
144
+
::
145
+
146
+
% git checkout master
122
147
123
-
Git checkout is the command to switch branches; this puts you on master branch, in the event you were sufficiently git-savy already to have created different branches in your git-cloned local repository. (It won’t hurt to type this if you are already on the master branch)
148
+
|Git checkout is the command to switch branches; this puts you on master branch, in the event you were sufficiently git-savy already to have created different branches in your git-cloned local repository. (It won’t hurt to type this if you are already on the master branch)
149
+
|
150
+
151
+
::
124
152
125
-
``git pull upstream master``
153
+
% git pull upstream master
126
154
127
-
This command will synchronize your local master branch with the main MITgcm repository master branch (i.e. “pull” any new changes that might have occurred in the upstream repository into your local clone). Note if you have made changes to files in the master branch, git will complain (files you created will not cause complaints, however) -- this is why we recommend doing other general MITgcm work (editing and running) on a separate branch and thus not working on the master branch. This command is necessary so that you use the most recently available code to begin your edits.
155
+
|This command will synchronize your local master branch with the main MITgcm repository master branch (i.e. “pull” any new changes that might have occurred in the upstream repository into your local clone). Note if you have made changes to files in the master branch, git will complain (files you created will not cause complaints, however) -- this is why we recommend doing other general MITgcm work (editing and running) on a separate branch and thus not working on the master branch. This command is necessary so that you use the most recently available code to begin your edits.
156
+
|
128
157
129
-
``git push origin master``
158
+
::
159
+
160
+
% git push origin master
130
161
131
-
The “push” command does the opposite of “pull”, so here you are synchronizing your GitHub cloud copy master branch to your local master branch (which you just updated). If you had performed step #1 above in the last few minutes, this step is not going to do anything (since you had just forked the “origin” from the “upstream” in step #1), but if any time elapsed, it will be necessary (the current version of the MITgcm source code is updated regularly).
162
+
|The “push” command does the opposite of “pull”, so here you are synchronizing your GitHub cloud copy master branch to your local master branch (which you just updated). If you had performed step #1 above in the last few minutes, this step is not going to do anything (since you had just forked the “origin” from the “upstream” in step #1), but if any time elapsed, it will be necessary (the current version of the MITgcm source code is updated regularly).
You will make edits on this new branch, to keep these new edits separate from any other changes to the repository in the course of your work (say through normal running of the model or any other separate research and/or modifications to repository files). Note that this command above not only creates the new branch ‘bugfix_thebug’ from the `upstream/master` branch, it switches you onto this newly created branch. Naming the branch something descriptive helps.
172
+
|You will make edits on this new branch, to keep these new edits separate from any other changes to the repository in the course of your work (say through normal running of the model or any other separate research and/or modifications to repository files). Note that this command above not only creates the new branch ‘bugfix_thebug’ from the `upstream/master` branch, it switches you onto this newly created branch. Naming the branch something descriptive helps.
173
+
|
140
174
141
175
5. Doing stuff! This usually comes in two flavors, fixing bugs or adding a feature. To do this you should:
142
176
@@ -147,16 +181,21 @@ A detailed explanation of steps for contributing MITgcm code edits:
147
181
148
182
6. Now we “push” our modified branch with committed changes onto the origin remote in the GitHub cloud. This effectively updates your GitHub cloud copy of the MITgcm repo to reflect the wonderful changes you are contributing.
149
183
150
-
``git push -u origin bugfix``
184
+
::
185
+
186
+
% git push -u origin bugfix
187
+
188
+
7. Finally create a “pull request” (a.k.a. “PR”; in other words, you are requesting that the maintainers pull your changes into the main code repository). In GitHub, go to the fork of the project that you made (https://github.com/user_name/MITgcm.git). There is a button for "Compare and Pull" in your newly created branch. Click the button! Now you can add a final succinct summary description of what you've done in your commit(s), and flag up any issues. At last the maintainers will be notified and be able to peruse your changes! While the PR remains open, you can go back to step #5 and make additional edits, git adds, git commits, and then redo step #6; such changes will be added to the PR (and maintainers re-notified).
151
189
152
-
7. Finally create a “pull request” (a.k.a. “PR”; in other words, you are requesting that the maintainers pull your changes into the main code repository). In GitHub, go to the fork of the project that you made (https://github.com/user_name/MITgcm66h.git). There is a button for "Compare and Pull" in your newly created branch. Click the button! Now you can add a final succinct summary description of what you've done in your commit(s), and flag up any issues. At last the maintainers will be notified and be able to peruse your changes! While the PR remains open, you can go back to step #5 and make additional edits, git adds, git commits, and then redo step #6; such changes will be added to the PR (and maintainers re-notified). The pull request remains open until either the maintainers fully accept and merge your code changes into the main repository, or decide to reject your changes. But much more likely than the latter, you will instead be asked to respond to feedback, modify your code changes in some way, and/or clean up your code to better satisfy our style requirements, etc., and the pull request will remain open instead of outright rejection.
190
+
Your pull request remains open until either the maintainers fully accept and merge your code changes into the main repository, or decide to reject your changes. But much more likely than the latter, you will instead be asked to respond to feedback, modify your code changes in some way, and/or clean up your code to better satisfy our style requirements, etc., and the pull request will remain open instead of outright rejection. It is possible for other users (besides the maintainers) to examine or even download your pull request; see :ref:`sec_pullreq`.
153
191
154
192
155
-
.. _subsec_code_style_guide:
193
+
.. _sec_code_style_guide:
156
194
157
-
Style guide
158
-
-----------
195
+
Coding style guide
196
+
==================
159
197
198
+
**Detailed instructions or link to be added.**
160
199
161
200
Automatic testing with Travis-CI
162
201
--------------------------------
@@ -166,7 +205,6 @@ The MITgcm uses the continuous integration service Travis-CI to test code before
166
205
**Detailed instructions or link to be added.**
167
206
168
207
169
-
170
208
Contributing to the manual
171
209
==========================
172
210
@@ -255,7 +293,7 @@ This information should go in an 'adominition' block. The source code to achieve
255
293
256
294
:math:`S_y`: **SlopeY** (argument on exit)
257
295
258
-
296
+
.. _sec_pullreq:
259
297
260
298
Reviewing pull requests
261
299
=======================
@@ -264,14 +302,33 @@ The only people with write access to the main repository are a small number of c
264
302
265
303
**Everyone can review and comment on pull requests.** Even if you are not one of the core developers you can still comment on a pull request.
266
304
267
-
To test pull requests locally you should:
305
+
To test pull requests locally you should download the pull request branch. You can do this either by cloning the branch from the pull request:
268
306
269
-
- add the repository of the user proposing the pull request as a remote, :code:`git remote add USERNAME https://github.com/USERNAME/MITgcm66h.git` where USERNAME is replaced by the user name of the person who has made the pull request;
- download a local version of the branch from the pull request, :code:`git fetch USERNAME` followed by :code:`git checkout --track USERNAME/foo`;
311
+
where `USERNAME` is replaced by the username of the person proposing the pull request, and `BRANCHNAME` is the branch from the pull request.
312
+
313
+
Alternatively, you can add the repository of the user proposing the pull request as a remote to your existing local repository. Move directories in to your local repository and then
where USERNAME is replaced by the user name of the person who has made the pull request. Then download the branch from the pull request
320
+
321
+
::
322
+
323
+
git fetch USERNAME
324
+
325
+
and switch to the desired branch
326
+
327
+
::
328
+
329
+
git checkout --track USERNAME/foo
272
330
273
-
- run tests locally; and
274
331
275
-
- possibly push fixes or changes directly to the pull request.
332
+
You now have a local copy of the code from the pull request and can run tests locally. If you have write access to the main repository you can push fixes or changes directly to the pull request.
276
333
277
-
None of these steps, apart from the final one, require write access to the main repository. This means that anyone can review pull requests. However, unless you are one of the core developers you won't be able to directly push changes. You will instead have to make a comment describing any problems you find.
334
+
None of these steps, apart from pushing fixes back to the pull request, require write access to either the main repository or the repository of the person proposing the pull request. This means that anyone can review pull requests. However, unless you are one of the core developers you won't be able to directly push changes. You will instead have to make a comment describing any problems you find.
0 commit comments