darwin3 |
|
|
|
|||
Warning, /doc/contributing/contributing.rst is written in an unsupported language. File is not indexed.
view on githubraw file Latest commit 003d2d85 on 2022-01-03 21:19:33 UTCaac9606f76 Jeff*0001 .. _chap_contributing: 0002 0003 Contributing to the MITgcm 0004 ************************** 0005 af61fa61c7 Jeff*0006 The MITgcm is an open source project that relies on the participation of its users, 0007 and we welcome contributions. This chapter sets out how you can contribute to the MITgcm. aac9606f76 Jeff*0008 0009 Bugs and feature requests 0010 ========================= 0011 af61fa61c7 Jeff*0012 If you think you've found a bug, the first thing to check that you're using the 0013 latest version of the model. If the bug is still in the latest version, then 0014 think about how you might fix it and file a ticket in the 0015 `GitHub issue tracker <https://github.com/MITgcm/MITgcm/issues>`_. Please 0016 include as much detail as possible. At a minimum your ticket should include: aac9606f76 Jeff*0017 0018 - what the bug does; 0019 - the location of the bug: file name and line number(s); and 0020 - any suggestions you have for how it might be fixed. 0021 af61fa61c7 Jeff*0022 To request a new feature, or guidance on how to implement it yourself, please 0023 open a ticket with the following details: 9061e4d211 Jean*0024 aac9606f76 Jeff*0025 - a clear explanation of what the feature will do; and 0026 - a summary of the equations to be solved. 0027 0028 .. _using_git_and_github: 0029 0030 Using Git and Github 0031 ======================== 0032 af61fa61c7 Jeff*0033 To contribute to the source code of the model you will need to fork the repository 0034 and place a pull request on GitHub. The two following sections describe this 0035 process in different levels of detail. If you are unfamiliar with git, you may 0036 wish to skip the quickstart guide and use the detailed instructions. All 0037 contributions to the source code are expected to conform with the 0038 :ref:`sec_code_style_guide`. Contributions to the manual should follow 0039 the same procedure and conform with :numref:`contrib_manual`. aac9606f76 Jeff*0040 0041 Quickstart Guide 0042 ---------------- 0043 f8d284a60d Jeff*0044 **0.** As a precursor, if you have not done so already, set up 0045 `ssh keys <https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh>`_ for GitHub 0046 `command line authentication <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github#authenticating-with-the-command-line>`_ 0047 (or alteratively, authenticate using a 0048 `personal access token <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token>`_). aac9606f76 Jeff*0049 f8d284a60d Jeff*0050 **1.** Fork the project on GitHub (using the fork button). 17d9efaae1 Edwa*0051 f8d284a60d Jeff*0052 **2.** Create a local clone (we strongly suggest keeping a separate 0053 repository for development work). If you are using ssh keys 0054 for command line authentication: aac9606f76 Jeff*0055 0056 :: 0057 204120b4cf Edwa*0058 % git clone git@github.com:«GITHUB_USERNAME»/MITgcm.git aac9606f76 Jeff*0059 f8d284a60d Jeff*0060 Alternatively, if you are using a personal access token for authentication: 0061 0062 :: 0063 0064 % git clone https://github.com/«GITHUB_USERNAME»/MITgcm.git 0065 0066 0067 **3.** Move into your local clone directory (cd MITgcm) and and set af61fa61c7 Jeff*0068 up a remote that points to the original: aac9606f76 Jeff*0069 0070 :: 0071 8a1a6e2b1a Ed D*0072 % git remote add upstream https://github.com/MITgcm/MITgcm.git aac9606f76 Jeff*0073 f8d284a60d Jeff*0074 **4.** Make a new branch from ``upstream/master`` (name it something af61fa61c7 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 76.
0075 appropriate, such as âbugfixâ or ânewfeatureâ etc.) and make edits on this branch: aac9606f76 Jeff*0076 0077 :: 0078 0079 % git fetch upstream af61fa61c7 Jeff*0080 % git checkout -b «YOUR_NEWBRANCH_NAME» upstream/master aac9606f76 Jeff*0081 f8d284a60d Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 83.
0082 **5.** When edits are done, do all git addâs and git commitâs. In the commit message, af61fa61c7 Jeff*0083 make a succinct (<70 char) summary of your changes. If you need more space to 0084 describe your changes, you can leave a blank line and type a longer description, 0085 or break your commit into multiple smaller commits. Reference any outstanding b843492ec3 Jeff*0086 issues addressed using the syntax ``#«ISSUE_NUMBER»``. aac9606f76 Jeff*0087 f8d284a60d Jeff*0088 **6.** Push the edited branch to the origin remote (i.e. your fork) on GitHub: aac9606f76 Jeff*0089 0090 :: 0091 af61fa61c7 Jeff*0092 % git push -u origin «YOUR_NEWBRANCH_NAME» aac9606f76 Jeff*0093 f8d284a60d Jeff*0094 **7.** On GitHub, go to your fork and hit the compare and pull request (PR) button, b843492ec3 Jeff*0095 provide the requested information about your PR (in particular, a non-trivial change to the model 0096 requires a suggested addition to :filelink:`doc/tag-index`) 003d2d851e Jeff*0097 and wait for the MITgcm head developers with merge privileges to review your proposed changes. 0098 In addition to the MITgcm head developers, a broader group of reviewers 0099 and developers will peruse and try to respond to a new PR within 0100 a week or two. The reviewers may accept the PR as is, or more typically, may request edits and aac9606f76 Jeff*0101 changes. Occasionally the review team will reject changes that are not 003d2d851e Jeff*0102 sufficiently aligned with and do not fit with the code structure. 0103 The review team is always happy to discuss their decision, but want to aac9606f76 Jeff*0104 avoid people investing extensive effort in code that has a fundamental 003d2d851e Jeff*0105 design flaw. As such, we **strongly** suggest opening an 0106 `issue <https://github.com/MITgcm/MITgcm/issues>`_ 0107 on GitHub to discuss any proposed contributions beforehand. 0108 0109 The current pull request discussion and review team is Jean-Michel Campin, 0110 Ed Doddridge, Chris Hill, Oliver Jahn, Jon Lauderdale, 0111 Martin Losch, Jeff Scott, Timothy Smith, and Ou Wang. Please 0112 contact anyone on this team with questions about a proposed pull request. aac9606f76 Jeff*0113 af61fa61c7 Jeff*0114 If you want to update your code branch before submitting a PR (or any point 0115 in development), follow the recipe below. It will ensure that your GitHub 0116 repo stays up to date with the main repository. Note again that your edits 0117 should always be to your development branch, not the master branch. aac9606f76 Jeff*0118 0119 :: 0120 0121 % git checkout master 0122 % git pull upstream master 0123 % git push origin master af61fa61c7 Jeff*0124 % git checkout «YOUR_NEWBRANCH_NAME» aac9606f76 Jeff*0125 % git merge master 0126 af61fa61c7 Jeff*0127 If you prefer, you can rebase rather than merge in the final step above; 9061e4d211 Jean*0128 just be careful regarding your rebase syntax! aac9606f76 Jeff*0129 0130 Detailed guide for those less familiar with Git and GitHub 0131 ---------------------------------------------------------- 0132 af61fa61c7 Jeff*0133 What is `Git <https://en.wikipedia.org/wiki/Git>`_? Git is a version 0134 control software tool used to help coordinate work among the many 0135 MITgcm model contributors. Version control is a management system to 0136 track changes in code over time, not only facilitating ongoing changes 0137 to code, but also as a means to check differences and/or obtain 0138 code from any past time in the project history. Without such a tool, 0139 keeping track of bug fixes and new features submitted by the global 0140 network of MITgcm contributors would be virtually impossible. If you 0141 are familiar with the older form of version control used by the 0142 MITgcm (CVS), there are many similarities, but we now take advantage 9061e4d211 Jean*0143 of the modern capabilities offered by Git. af61fa61c7 Jeff*0144 0145 Git itself is open source linux software (typically included with any 0146 new linux installation, check with your sys-admin if it seems to be 0147 missing) that is necessary for tracking changes in files, etc. through** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 149.
0148 your local computerâs terminal session. All Git-related terminal commands 0149 are of the form ``git «arguments»``. Important functions include syncing 0150 or updating your code library, adding files to a collection of files** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 152.
0151 with edits, and commands to âfinalizeâ these changes for sending back to 003d2d851e Jeff*0152 the MITgcm head developers. There are numerous other Git command-line af61fa61c7 Jeff*0153 tools to help along the way (see man pages via ``man git``). aac9606f76 Jeff*0154 0155 The most common git commands are: 0156 0157 - ``git clone`` download (clone) a repository to your local machine 0158 - ``git status`` obtain information about the local git repository 0159 - ``git diff`` highlight differences between the current version of a file and the version from the most recent commit 0160 - ``git add`` stage a file, or changes to a file, so that they are ready for ``git commit`` 0161 - ``git commit`` create a commit. A commit is a snapshot of the repository with an associated message that describes the changes. 0162 b843492ec3 Jeff*0163 What is GitHub then? GitHub is a website that has three major purposes: 1) Code Viewer: through your browser, you can view** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 165.
0164 all source code and all changes to such over time; 2) âPull Requestsâ: facilitates the process whereby code developers submit 003d2d851e Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 166.
0165 changes to the primary MITgcm head developers; 3) the âCloudâ: GitHub functions as a cloud server to store different copies of the code. b843492ec3 Jeff*0166 The utility of #1 is fairly obvious. For #2 and #3, without GitHub, one might envision making a big tarball of edited files and 003d2d851e Jeff*0167 emailing the head developers for inclusion in the main repository. Instead, GitHub effectively does something like this for you in a b843492ec3 Jeff*0168 much more elegant way. Note unlike using (linux terminal command) git, GitHub commands are NOT typed in a terminal, but are f8d284a60d Jeff*0169 typically invoked by hitting a button on the web interface, or clicking on a webpage link etc. 0170 0171 To contribute edits to MITgcm,** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 173.
0172 **the first step is to obtain a GitHub account**, if you have not done so already; itâs free. Second, as a 'developer' you will need to 0173 `authenticate <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github#authenticating-with-the-command-line>`_ 0174 your terminal command line sessions in GitHub. There are two ways this can be done, either using 0175 `ssh keys <https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh>`_ 0176 or via a `personal access token <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token>`_. 0177 A personal access token functions similar to a password; ssh keys require some upfront configuration 0178 (`generating the key <https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent>`_ 0179 and then `adding to your Github account <https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account>`_), 0180 but most developers prefer the ease of this approach once it is set up. aac9606f76 Jeff*0181 0182 Before you start working with git, make sure you identify yourself. From your terminal, type: 0183 0184 :: 0185 af61fa61c7 Jeff*0186 % git config --global user.email «your_email@example.edu»** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 188.
0187 % git config --global user.name «âJohn Doeâ» aac9606f76 Jeff*0188 0189 (note the required quotes around your name). You should also personalize your profile associated with your GitHub account. 0190 b843492ec3 Jeff*0191 There are many online tutorials to using Git and GitHub 0192 (see for example https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project ); 0193 here, we are just communicating the basics necessary to submit code changes to the MITgcm. Spending some time learning the more 0194 advanced features of Git will likely pay off in the long run, and not just for MITgcm contributions, 0195 as you are likely to encounter it in all sorts of different projects. aac9606f76 Jeff*0196 b843492ec3 Jeff*0197 To better understand this process, :numref:`git_setup` shows a conceptual map of the Git setup. Note three copies of the code: 003d2d851e Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 199.
0198 the main MITgcm repository sourcecode âupstreamâ (i.e., owned by the MITgcm head developers) in the GitHub cloud, a copy of the b843492ec3 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 200.
0199 repository âoriginâ owned by you, also residing in the GitHub cloud, and a local copy on your personal computer or compute cluster 0200 (where you intend to compile and run). The Git and GitHub commands to create this setup are explained more fully below. aac9606f76 Jeff*0201 0202 .. figure:: figs/git_setup.* 0203 :width: 70% 0204 :align: center 0205 :alt: Conceptual model of GitHub 0206 :name: git_setup 0207 0208 A conceptual map of the GitHub setup. Git terminal commands are shown in red, GitHub commands are shown in green. 0209 af61fa61c7 Jeff*0210 One other aspect of Git that requires some explanation to the uninitiated: your** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 212.
0211 local linux copy of the code repository can contain different âbranchesâ, 0212 each branch being a different copy of the code repository (this can occur 0213 in all git-aware directories). When you switch branches, basic unix commands 0214 such as ``ls`` or ``cat`` will show a different set of files specific to 0215 current branch. In other words, Git interacts with your local file system 0216 so that edits or newly created files only appear in the current branch, i.e., 0217 such changes do not appear in any other branches. So if you swore you 0218 made some changes to a particular file, and now it appears those changes 0219 have vanished, first check which branch you are on (``git status`` is a b843492ec3 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 221.
0220 useful command here), all is probably not lost. NOTE: for a file to be âassignedâ to a specific Git branch,** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 222.
0221 Git must first be âmade awareâ of the file, which occurs after a ``git add`` and ``git commit`` (see :ref:`below <doing_stuff_in_git>`). 0222 Prior to this, the file will appear in the current folder independently, i.e., regardless of which git branch you are on. aac9606f76 Jeff*0223 0224 A detailed explanation of steps for contributing MITgcm repository edits: 0225 f8d284a60d Jeff*0226 **1.** On GitHub, create a local copy of the repository in your GitHub cloud user space: af61fa61c7 Jeff*0227 from the main repository (https://github.com/MITgcm/MITgcm) hit the **Fork** button.** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 229.
0228 As mentioned, your GitHub copy âoriginâ is necessary to streamline the collaborative 0229 development process -- you need to create a place for your edits in the GitHub cloud, f8d284a60d Jeff*0230 for developers to peruse. (Note: this step is only necessary the first time you contribute a pull request, 0231 as this forked copy will remain permanently in your Github space.) aac9606f76 Jeff*0232 f8d284a60d Jeff*0233 **2.** Download the code onto your local computer using the git clone command. af61fa61c7 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 235.
0234 Even if you previously downloaded the code through a âgit-awareâ method 0235 (i.e., a git clone command, see :numref:`git-aware_download`), 0236 we **STRONGLY SUGGEST** you download a fresh repository, to a separate f8d284a60d Jeff*0237 disk location, for your development work (keeping your research work separate). 0238 If you are using ssh keys for command line authentication (see above), in your terminal window type: aac9606f76 Jeff*0239 0240 :: 0241 204120b4cf Edwa*0242 % git clone git@github.com:«GITHUB_USERNAME»/MITgcm.git aac9606f76 Jeff*0243 f8d284a60d Jeff*0244 Alternatively, if you are using a personal access token for authentication: 0245 0246 :: 0247 0248 % git clone https://github.com/«GITHUB_USERNAME»/MITgcm.git 0249 0250** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 252.
0251 (technically, here you are copying the forked âoriginâ af61fa61c7 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 253.
0252 version from the cloud, not the âupstreamâ version, but these will be identical at this point). aac9606f76 Jeff*0253 f8d284a60d Jeff*0254 **3.** Move into the local clone directory on your computer: aac9606f76 Jeff*0255 0256 :: 0257 0258 % cd MITgcm 0259 0260 We need to set up a remote that points to the main repository: 0261 0262 :: 0263 8a1a6e2b1a Ed D*0264 % git remote add upstream https://github.com/MITgcm/MITgcm.git aac9606f76 Jeff*0265 af61fa61c7 Jeff*0266 This means that we now have two "remotes" of the project. A remote is 0267 just a pointer to a repository not on your computer, i.e., in the GitHub** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 269.
0268 cloud, one pointing to your GitHub user space (âoriginâ), and this new** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 270.
0269 remote pointing to the original (âupstreamâ). You can read and write 0270 into your "origin" version (since it belongs to you, in the cloud), 0271 but not into the "upstream" version. This command just sets up this 0272 remote, which is needed in step #4 -- no actual file manipulation 0273 is done at this point. If in doubt, the command ``git remote -v`` 0274 will list what remotes have been set up. aac9606f76 Jeff*0275 f8d284a60d Jeff*0276 **4.** Next make a new branch. aac9606f76 Jeff*0277 0278 :: 9061e4d211 Jean*0279 aac9606f76 Jeff*0280 % git fetch upstream af61fa61c7 Jeff*0281 % git checkout -b «YOUR_NEWBRANCH_NAME» upstream/master 0282 0283 You will make edits on this new branch, to keep these new edits completely 0284 separate from all files on the master branch. The first command 0285 ``git fetch upstream`` makes sure your new branch is the latest code f8d284a60d Jeff*0286 from the main repository; as such, you can redo step 4 at any time to af61fa61c7 Jeff*0287 start additional, separate development projects (on a separate, new branch). 0288 Note that this second command above not only creates this new branch, 0289 from the ``upstream/master`` branch, it also switches you onto this newly** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 291.
0290 created branch. Naming the branch something descriptive like ânewfeatureâ 9061e4d211 Jean*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 292.
0291 or âbugfixâ (preferably, be even more descriptive) is helpful. 0292 b843492ec3 Jeff*0293 .. _doing_stuff_in_git: aac9606f76 Jeff*0294 f8d284a60d Jeff*0295 **5.** Doing stuff! This usually comes in one of three flavors: aac9606f76 Jeff*0296 9061e4d211 Jean*0297 | i) cosmetic changes, formatting, documentation, etc.; 0298 | ii) fixing bug(s), or any change to the code which results in different numerical output; or aac9606f76 Jeff*0299 | iii) adding a feature or new package. 9061e4d211 Jean*0300 | aac9606f76 Jeff*0301 | To do this you should: 0302 b843492ec3 Jeff*0303 - edit the relevant file(s) and/or create new files. Refer to :ref:`sec_code_style_guide` for details on expected documentation 0304 standards and code style requirements. Of course, changes should be thoroughly tested to ensure they compile and run successfully! 0305 - type ``git add «FILENAME1» «FILENAME2» ...`` to stage the file(s) ready for a commit command (note both existing and** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 307.
0306 brand new files need to be added). âStageâ effectively means to notify Git of the the list of files you plan to âcommitâ 0307 for changes into the version tracking system. Note you can change other files and NOT have them sent to model developers; 0308 only staged files will be sent. You can repeat this ``git add`` command as many times as you like and it will continue 0309 to augment the list of files. ``git diff`` and ``git status`` are useful commands to see what you have done so far. 0310 - use ``git commit`` to commit the files. This is the first step in bundling a collection of files together to be sent 003d2d851e Jeff*0311 off to the MITgcm head developers. When you enter this command, an editor window will pop up. On the top line, type a succinct b843492ec3 Jeff*0312 (<70 character) summary of what these changes accomplished. If your commit is non-trivial and additional explanation is required, 0313 leave a blank line and then type a longer description of why the action in this commit was appropriate etc. 0314 It is good practice to link with known issues using the syntax ``#ISSUE_NUMBER`` in either the summary line or detailed comment. 0315 Note that all the changes do not have to be handled in a single commit (i.e. you can git add some files, do a commit, 0316 than continue anew by adding different files, do another commit etc.); the ``git commit`` command itself does 003d2d851e Jeff*0317 not (yet) submit anything to head developers. b843492ec3 Jeff*0318 - if you are fixing a more involved bug or adding a new feature, such that many changes are required, 0319 it is preferable to break your contribution into multiple commits (each documented separately) rather than submitting one massive commit; 0320 each commit should encompass a single conceptual change to the code base, regardless of how many files it touches. 003d2d851e Jeff*0321 This will allow the MITgcm head developers to more easily understand your proposed changes and will expedite the review process. b843492ec3 Jeff*0322 f8d284a60d Jeff*0323 When your changes are tested and documented, continue on to step #6, but read all of step #6 and #7 before proceeding;** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 325.
0324 you might want to do an optional âbring my development branch up to dateâ sequence of steps before step #6. b843492ec3 Jeff*0325 f8d284a60d Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 327.
0326 **6.** Now we âpushâ our modified branch with committed changes onto the origin remote in the GitHub cloud. b843492ec3 Jeff*0327 This effectively updates your GitHub cloud copy of the MITgcm repo to reflect the wonderful changes you are contributing. aac9606f76 Jeff*0328 0329 :: 0330 af61fa61c7 Jeff*0331 % git push -u origin «YOUR_NEWBRANCH_NAME» aac9606f76 Jeff*0332 f8d284a60d Jeff*0333 Some time might elapse during step #5, as you make and test your edits, during which continuing development occurs in the main MITgcm repository. b843492ec3 Jeff*0334 In contrast with some models that opt for static, major releases, the MITgcm is in a constant state of improvement and development. 0335 It is very possible that some of your edits occur to files that have also been modified by others. Your local clone however will not f8d284a60d Jeff*0336 know anything about any changes that may have occurred to the MITgcm repo in the cloud, which may cause an issue in step #7 below, b843492ec3 Jeff*0337 when one of three things will occur: 9061e4d211 Jean*0338 b843492ec3 Jeff*0339 - the files you have modified in your development have **NOT** been modified in the main repo during this elapsed time, 0340 thus git will have no conflicts in trying to update (i.e. merge) your changes into the main repo. 0341 - during the elapsed time, the files you have modified have also been edited/updated in the main repo, 0342 but you edited different places in these files than those edits to the main repo, such that git is 0343 smart enough to be able to merge these edits without conflict. 0344 - during the elapsed time, the files you have modified have also been edited/updated in the main repo, 0345 but git is not smart enough to know how to deal with this conflict (it will notify you of this problem during step #7). 0346 f8d284a60d Jeff*0347 One option is to NOT attempt to bring your development code branch up to date, instead simply proceed with steps #6 and #7 and 003d2d851e Jeff*0348 let the maintainers (i.e., the MITgcm head developers with merge priviledges) assess and resolve any conflict(s),** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 350.
0349 should such occur (there is a checkbox âAllow edits by maintainersâ f8d284a60d Jeff*0350 that is checked by default when you do step #7). If very little time elapsed during step #5, such conflict is less likely. 0351 However, if step #5 takes on the order of months, we do suggest you follow this recipe below to update the code and merge yourself. b843492ec3 Jeff*0352 And/or during the development process, you might have reasons to bring the latest changes in the main repo into your 0353 development branch, and thus might opt to follow these same steps. aac9606f76 Jeff*0354 0355 Development branch code update recipe: 0356 0357 :: 0358 0359 % git checkout master 0360 % git pull upstream master 0361 % git push origin master af61fa61c7 Jeff*0362 % git checkout «YOUR_NEWBRANCH_NAME» aac9606f76 Jeff*0363 % git merge master 9061e4d211 Jean*0364 b843492ec3 Jeff*0365 This first command switches you from your development branch to the master branch. The second command above will synchronize** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 367.
0366 your local master branch with the main MITgcm repository master branch (i.e. âpullâ any new changes that might have occurred** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 368.
0367 in the upstream repository into your local clone). Note you should not have made any changes to your cloneâs master branch; f8d284a60d Jeff*0368 in other words, prior to the pull, master should be a stagnant copy of the code from the day you performed step #1 above. b843492ec3 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 370.
0369 The ``git push`` command does the opposite of pull, so in the third step you are synchronizing your GitHub cloud copy (âoriginâ)** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 371.
0370 master branch to your local cloneâs master branch (which you just updated). Then, switch back to your development branch via 0371 the second ``git checkout`` command. Finally, the last command will merge any changes into your development branch. 0372 If conflicts occur that git cannot resolve, git will provide you a list of the problematic file names, and in these files,** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 374.
0373 areas of conflict will be demarcated. You will need to edit these files at these problem spots (while removing gitâs demarcation text), 9061e4d211 Jean*0374 then do a ``git add «FILENAME»`` for each of these files, followed by a final ``git commit`` to finish off the merger. aac9606f76 Jeff*0375 b843492ec3 Jeff*0376 Some additional ``git diff`` commands to help sort out file changes, in case you want to assess the scope of development changes, 0377 are as follows. ``git diff master upstream/master`` will show you all differences between your local master branch and the main 0378 MITgcm repo, i.e., so you can peruse what parallel MITgcm changes have occurred while you were doing your development (this assumes** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 380.
0379 you have not yet updated your cloneâs master branch). 0380 You can check for differences on individual files via ``git diff master upstream/master «FILENAME»``. 0381 If you want to see all differences in files you have modified during your development, the command 9061e4d211 Jean*0382 is ``git diff master``. Similarly, to see a combined list of both your changes and those occurring to the main repo, ``git diff upstream/master``. b843492ec3 Jeff*0383** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 385.
0384 Aside comment: if you are familiar with git, you might realize there is an alternate way to merge, using the ârebaseâ syntax. 0385 If you know what you are doing, feel free to use this command instead of our suggested merge command above. 0386 003d2d851e Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 388.
0387 **7.** Finally create a âpull requestâ (a.k.a. âPRâ; in other words, you are requesting that the 0388 MITgcm head developers with merge privileges pull your changes into the main code repository). b843492ec3 Jeff*0389 In GitHub, go to the fork of the project that you made (https://github.com/«GITHUB_USERNAME»/MITgcm.git). 0390 There is a button for "Compare and Pull" in your newly created branch. Click the button! 0391 Now you can add a final succinct summary description of what you've done in your commit(s), 0392 flag up any issues, and respond to the remaining questions on the PR template form. If you have made non-trivial changes to 0393 the code or documentation, we will note this in the MITgcm change log, :filelink:`doc/tag-index`. Please suggest how to note your 003d2d851e Jeff*0394 changes in :filelink:`doc/tag-index`; we will not accept the PR if this field is left blank. 0395 The MITgcm PR discussion team (in addition to the MITgcm head developers, a broader group of reviewers) will now be notified 0396 and be able to peruse your changes! In general, the PR review team will try to respond to a new PR within a week or two. 0397 While the PR remains open, you can go back to step #5 and make additional edits, git adds, 0398 git commits, and then redo step #6; such changes will be added to the PR (and head developers re-notified), no need to redo step #7. aac9606f76 Jeff*0399 003d2d851e Jeff*0400 Your pull request remains open until either the MITgcm head developers with merge privileges fully accept and b843492ec3 Jeff*0401 merge your code changes into the main repository, or decide to reject your changes. 0402 Occasionally, the review team will reject changes that are not 0403 sufficiently aligned with and do not fit with the code structure; 003d2d851e Jeff*0404 the review team is always happy to discuss their decision, but want to b843492ec3 Jeff*0405 avoid people investing extensive additional effort in code that has a fundamental design flaw. 9061e4d211 Jean*0406 But much more likely than outright rejection, you will instead be asked to respond to feedback, aac9606f76 Jeff*0407 modify your code changes in some way, and/or clean up your code to better satisfy our style requirements, etc., 9061e4d211 Jean*0408 and the pull request will remain open. 003d2d851e Jeff*0409 In some cases, the head developers might take initiative to make some changes to your pull request b843492ec3 Jeff*0410 (such changes can then be incorporated back into your local branch simply by typing ``git pull`` from your branch), but 0411 more typically you will be asked to undertake the majority of the necessary changes. 003d2d851e Jeff*0412 Note we **strongly** suggest opening an `issue <https://github.com/MITgcm/MITgcm/issues>`_ 0413 on GitHub to discuss any proposed contributions beforehand. aac9606f76 Jeff*0414 003d2d851e Jeff*0415 It is possible for other users (besides the PR review team) to examine aac9606f76 Jeff*0416 or even download your pull request; see :ref:`sec_pullreq`. 0417 003d2d851e Jeff*0418 The current pull request discussion and review team is Jean-Michel Campin, 0419 Ed Doddridge, Chris Hill, Oliver Jahn, Jon Lauderdale, 0420 Martin Losch, Jeff Scott, Timothy Smith, and Ou Wang. Please feel free 0421 to contact anyone on this team with questions about a proposed pull request. aac9606f76 Jeff*0422 0423 .. _sec_code_style_guide: 0424 0425 Coding style guide 0426 ================== 0427 0428 **Detailed instructions or link to be added.** 0429 b843492ec3 Jeff*0430 Creating MITgcm packages 0431 ======================== 0432 0433 Optional parts of code are separated from 0434 the MITgcm core driver code and organized into 0435 packages. The packaging structure provides a mechanism for 0436 maintaining suites of code, specific to particular 0437 classes of problem, in a way that is cleanly 0438 separated from the generic fluid dynamical engine. An overview of available MITgcm 0439 packages is presented in :numref:`packagesI`, as illustrated in :numref:`fig_package_organigramme`. 0440 An overview of how to include and use MITgcm packages in your setup is presented in :numref:`using_packages`, 0441 with specific details on using existing packages spread throughout :numref:`packagesI`, :numref:`outp_pack`, and :numref:`chap_state_estimation`. 0442 This sub-section includes information necessary to create your own package for use with MITgcm. 0443 0444 The MITgcm packaging structure is described 0445 below using generic package names ``${pkg}``. 0446 A concrete examples of a package is the code 0447 for implementing GM/Redi mixing: this code uses 0448 the package names ``${PKG} = GMREDI``, ``${pkg} = gmredi``, and ``${Pkg} = gmRedi``. 0449 0450 Package structure 0451 ----------------- 0452** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 454.
0453 âą Compile-time state: Given that each package is allowed to be compiled or not 0454 (e.g., all ``${pkg}`` listed in ``packages.conf`` are compiled, see :numref:`pkg_inclusion_exclusion`), 0455 :filelink:`genmake2 <tools/genmake2>` keeps track of each package's compile-state in PACKAGES_CONFIG.h 0456 with CPP option ``ALLOW_${PKG}`` being defined (``#define``) or not (``#undef``). 0457 Therefore, in the MITgcm core code (or code from other included packages), calls to package-specific 0458 subroutines and package-specific header file ``#include`` statements 0459 must be protected within ``#ifdef ALLOW_${PKG}`` ... ... ``#endif /* ALLOW_${PKG} */`` 9061e4d211 Jean*0460 (see :ref:`below <example_pkg_call_from_outside>`) to ensure that the model compiles when this ${pkg} b843492ec3 Jeff*0461 is not compiled. 0462** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 464.
0463 âą Run-time state: The core driver part of the model can check 0464 for a run-time on/off switch of individual package(s) 0465 through the Fortran logical flag ``use${Pkg}``. 0466 The information is loaded from a 0467 global package setup file called ``data.pkg``. Note a 0468 ``use${Pkg}`` flag is NOT used within the 0469 package-local subroutine code (i.e., ``${pkg}_«DO_SOMETHING».F`` package source code). 0470** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 472.
0471 âą Each package gets its runtime configuration 0472 parameters from a file named ``data.${pkg}``. 0473 Package runtime configuration options are imported 0474 into a common block held in a header file 0475 called ``${PKG}.h``. 0476 Note in some packages, the header file ``${PKG}.h`` is split 0477 into ``${PKG}_PARAMS.h``, which contains the package parameters, and 0478 ``${PKG}_VARS.h`` for the field arrays. The ``${PKG}.h`` header file(s) can be imported 0479 by other packages to check dependencies and requirements 0480 from other packages (see :numref:`package_boot_sequence`). 0481** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 483.
0482 In order for a packageâs run-time state ``use${Pkg}`` to be set to true (i.e., âonâ),** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 484.
0483 the code build must have its compile-time state ``ALLOW_${PKG}`` defined (i.e., âincludedâ),** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 485.
0484 else mitgcmuv will terminate (cleanly) during initialization. A packageâs run-time state 9061e4d211 Jean*0485 is not permitted to change during a model run. b843492ec3 Jeff*0486 0487 Every call to a package routine from **outside** the package 0488 requires a check on BOTH compile-time and run-time states: 0489 0490 .. _example_pkg_call_from_outside: 0491 0492 :: 0493 0494 #include "PACKAGES_CONFIG.h" 0495 #include "CPP_OPTIONS.h" 0496 . 0497 . 0498 #ifdef ALLOW_${PKG} 0499 # include "${PKG}_PARAMS.h" 9061e4d211 Jean*0500 #endif b843492ec3 Jeff*0501 . 0502 . 0503 . 0504 0505 #ifdef ALLOW_${PKG} 9061e4d211 Jean*0506 IF ( use${Pkg} ) THEN b843492ec3 Jeff*0507 . 0508 . 0509 CALL ${PKG}_DO_SOMETHING(...) 0510 . 9061e4d211 Jean*0511 ENDIF b843492ec3 Jeff*0512 #endif 0513 0514 **Within** an individual package, the header file ``${PKG}_OPTIONS.h`` 0515 is used to set CPP flags specific to that package. This header file should include 0516 ``PACKAGES_CONFIG.h`` and :filelink:`CPP_OPTIONS.h <model/inc/CPP_OPTIONS.h>`, as shown in this example: 0517 0518 :: 0519 0520 #ifndef ${PKG}_OPTIONS_H 0521 #define ${PKG}_OPTIONS_H 0522 #include "PACKAGES_CONFIG.h" 0523 #include "CPP_OPTIONS.h" 9061e4d211 Jean*0524 b843492ec3 Jeff*0525 #ifdef ALLOW_${PKG} 0526 . 0527 . 0528 . 0529 #define ${PKG}_SOME_PKG_SPECIFIC_CPP_OPTION 0530 . 0531 . 0532 . 0533 #endif /* ALLOW_${PKG} */ 0534 #endif /* ${PKG}_OPTIONS_H */ 0535 0536 See for example :filelink:`GMREDI_OPTIONS.h <pkg/gmredi/GMREDI_OPTIONS.h>`. 0537 0538 .. _package_boot_sequence: 0539 0540 Package boot sequence 0541 --------------------- 0542 0543 All packages follow a required "boot" sequence outlined here: 0544 0545 :: 0546 0547 S/R PACKAGES_BOOT() 0548 0549 S/R PACKAGES_READPARMS() 0550 #ifdef ALLOW_${PKG} 0551 IF ( use${Pkg} ) CALL ${PKG}_READPARMS( retCode ) 0552 #endif 0553 0554 S/R PACKAGES_INIT_FIXED() 0555 #ifdef ALLOW_${PKG} 0556 IF ( use${Pkg} ) CALL ${PKG}_INIT_FIXED( retCode ) 0557 #endif 0558 0559 S/R PACKAGES_CHECK() 0560 #ifdef ALLOW_${PKG} 0561 IF ( use${Pkg} ) CALL ${PKG}_CHECK( retCode ) 0562 #else 0563 IF ( use${Pkg} ) CALL PACKAGES_CHECK_ERROR('${PKG}') 0564 #endif 0565 0566 S/R PACKAGES_INIT_VARIABLES() 0567 #ifdef ALLOW_${PKG} 0568 IF ( use${Pkg} ) CALL ${PKG}_INIT_VARIA( ) 0569 #endif 0570 0571 - :filelink:`PACKAGES_BOOT() <model/src/packages_boot.F>` 0572 determines the logical state of all ``use${Pkg}`` variables, as defined in the file ``data.pkg``. 0573 0574 - ${PKG}_READPARMS() 0575 is responsible for reading 0576 in the package parameters file ``data.${pkg}`` and storing 0577 the package parameters in ``${PKG}.h`` (or in ``${PKG}_PARAMS.h``). 0578 ${PKG}_READPARMS is called in S/R :filelink:`packages_readparms.F <model/src/packages_readparms.F>`, 0579 which in turn is called from S/R :filelink:`initialise_fixed.F <model/src/initialise_fixed.F>`. 0580 0581 - ${PKG}_INIT_FIXED() 0582 is responsible for completing the internal setup of a package, including adding any package-specific 0583 variables available for output in :filelink:`pkg/diagnostics` (done in S/R ${PKG}_DIAGNOSTICS_INIT). 0584 ${PKG}_INIT_FIXED is called in S/R :filelink:`packages_init_fixed.F <model/src/packages_init_fixed.F>`, 0585 which in turn is called from S/R :filelink:`initialise_fixed.F <model/src/initialise_fixed.F>`. 0586 Note: some packages instead use ``CALL ${PKG}_INITIALISE`` (or the old form ``CALL ${PKG}_INIT``). 9061e4d211 Jean*0587 b843492ec3 Jeff*0588 - ${PKG}_CHECK() 0589 is responsible for validating 0590 basic package setup and inter-package dependencies. 0591 ${PKG}_CHECK can also import parameters from other packages that it may 0592 need to check; this is accomplished through header files ``${PKG}.h``. 0593 (It is assumed that parameters owned by other packages 0594 will not be reset during ${PKG}_CHECK !!!) 0595 ${PKG}_CHECK is called in S/R :filelink:`packages_check.F <model/src/packages_check.F>`, 0596 which in turn is called from S/R :filelink:`initialise_fixed.F <model/src/initialise_fixed.F>`. 0597 0598 - ${PKG}_INIT_VARIA() 0599 is responsible for initialization of all package variables, called after the core model state has been completely 0600 initialized but before the core model timestepping starts. 0601 This routine calls ${PKG}_READ_PICKUP, where any package variables required to restart the model 0602 will be read from a pickup file. 0603 ${PKG}_INIT_VARIA is called in :filelink:`packages_init_variables.F <model/src/packages_init_variables.F>`, 0604 which in turn is called from S/R :filelink:`initialise_varia.F <model/src/initialise_varia.F>`. 0605 Note: the name ${PKG}_INIT_VARIA is not yet standardized across all packages; 0606 one can find other S/R names such as ${PKG}_INI_VARS or ${PKG}_INIT_VARIABLES or ${PKG}_INIT. 0607 0608 Package S/R calls 0609 ----------------- 0610 0611 Calls to package subroutines within the core code timestepping 9061e4d211 Jean*0612 loop can vary. Below we show an example of calls to do calculations, generate output 0613 and dump the package state (for pickup): b843492ec3 Jeff*0614 0615 :: 0616 0617 S/R DO_OCEANIC_PHYS() 0618 #ifdef ALLOW_${PKG} 0619 IF ( use${Pkg} ) CALL ${PKG}_DO_SOMETHING( ) 0620 #endif 0621 0622 S/R DO_THE_MODEL_IO() 0623 #ifdef ALLOW_${PKG} 0624 IF ( use${Pkg} ) CALL ${PKG}_OUTPUT( ) 0625 #endif 0626 0627 S/R PACKAGES_WRITE_PICKUP() 0628 #ifdef ALLOW_${PKG} 0629 IF ( use${Pkg} ) CALL ${PKG}_WRITE_PICKUP( ) 0630 #endif 0631 0632 - ${PKG}_DO_SOMETHING() 0633 refers to any local package source code file, which may be called from any :filelink:`model/src` routine 9061e4d211 Jean*0634 (or, from any subroutine in another package). An specific example would be the b843492ec3 Jeff*0635 S/R call :filelink:`gmredi_calc_tensor.F <pkg/gmredi/gmredi_calc_tensor.F>` from within the core S/R 0636 :filelink:`model/src/do_oceanic_phys.F`. 0637 0638 - ${PKG}_OUTPUT() 0639 is responsible for writing time-average fields to output files 0640 (although the cumulating step is done within other package subroutines). 0641 May also call other output routines (e.g., CALL ${PKG}_MONITOR) 0642 and write snapshot fields that are held in common blocks. Other 0643 temporary fields are directly dumped to file where they are available. 9061e4d211 Jean*0644 Note that :filelink:`pkg/diagnostics` output of ${PKG} variables b843492ec3 Jeff*0645 is generated in :filelink:`pkg/diagnostics` subroutines. 0646 ${PKG}_OUTPUT() is called in S/R :filelink:`do_the_model_io.F <model/src/do_the_model_io.F>` 0647 NOTE: 1) the S/R ${PKG}_DIAGS is used in some packages 0648 but is being replaced by ${PKG}_OUTPUT 0649 to avoid confusion with :filelink:`pkg/diagnostics` functionality. 0650 2) the output part is not yet in a standard form. 0651 0652 - ${PKG}_WRITE_PICKUP() 0653 is responsible for writing a package pickup file, used in packages where such is necessary for 0654 a restart. ${PKG}_WRITE_PICKUP is called in :filelink:`packages_write_pickup.F <model/src/packages_write_pickup.F>` 0655 which in turn is called from :filelink:`the_model_main.F <model/src/the_model_main.F>`. 0656 0657 Note: In general, subroutines in one package (pkgA) that only contains code which 0658 is connected to a 2nd package (pkgB) will be named pkgA_pkgB_something.F 0659 (e.g., :filelink:`gmredi_diagnostics_init.F <pkg/gmredi/gmredi_diagnostics_init.F>`). 0660** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 662.
0661 Package âmypackageâ 0662 ------------------- 0663 0664 In order to simply creating the infrastructure required for a new package, we have created :filelink:`pkg/mypackage` 0665 as essentially an existing package (i.e., all package variables defined, proper boot sequence, output generated) that** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 667.
0666 does not do anything. Thus, we suggest you start with this âblankâ packageâs code infrastructure and add your new package functionality 0667 to it, perusing the existing mypackage routines and editing as necessary, rather than creating a new package from scratch. 0668 1c87316fba Jeff*0669 .. _code_testing_protocols: b843492ec3 Jeff*0670 0671 MITgcm code testing protocols 0672 ============================= 0673 0674 :filelink:`verification` directory includes many examples 0675 intended for regression testing (some of which are tutorial experiments presented in detail in :numref:`chap_modelExamples`). 0676 Each one of these test-experiment directories contains "known-good" standard output files (see :numref:`reference_output`) 0677 along with all the input (including both code and data files) required for their re-calculation. Also included in 0678 :filelink:`verification` is the shell script :filelink:`testreport <verification/testreport>` to perform regression tests. 0679 0680 Test-experiment directory content 0681 --------------------------------- 0682 0683 Each test-experiment directory («TESTDIR», see :filelink:`verification` for 0684 the full list of choices) contains several standard subdirectories and files which 0685 :filelink:`testreport <verification/testreport>` recognizes and uses when running a regression test. 0686 The directories and files that :filelink:`testreport <verification/testreport>` 0687 uses are different for a forward test and an adjoint test (``testreport -adm``, see :numref:`testreport_utility`) and 0688 some test-experiments are set-up for only one type of regression test 0689 whereas others allow both types of tests (forward and adjoint). 0690 Also some test-experiments allow, using the same MITgcm executable, multiple tests using 0691 different parameters and input files, with a primary input set-up (e.g., ``input/`` or ``input_ad/``) and corresponding 0692 results (e.g., ``results/output.txt`` or ``results/output_adm.txt``) and with one or several secondary inputs 0693 (e.g., ``input.«OTHER»/`` or ``input_ad.«OTHER»/``) and corresponding results (e.g., ``results/output.«OTHER».txt`` or ``results/output_adm.«OTHER».txt``). 0694 1c8cebb321 Jeff*0695 directory «TESTDIR»/code/ b843492ec3 Jeff*0696 Contains the test-experiment specific source code (i.e., files that have been modified from the standard 0697 MITgcm repository version) used to build the MITgcm executable (``mitgcmuv``) 0698 for forward-test (using ``genmake2 -mods=../code``). 9061e4d211 Jean*0699 b843492ec3 Jeff*0700 It can also contain specific source files with the suffix ``_mpi`` to be used in place of the corresponding file 0701 (without suffix) for an MPI test (see :numref:`testreport_utility`). The presence or absence of ``SIZE.h_mpi`` 9061e4d211 Jean*0702 determines whether or not an MPI test on this test-experiment is performed or skipped. b843492ec3 Jeff*0703 Note that the original ``code/SIZE.h_mpi`` 0704 is not directly used as :filelink:`SIZE.h <model/inc/SIZE.h>` to build an MPI-executable; instead, a local copy 0705 ``build/SIZE.h.mpi`` is derived from ``code/SIZE.h_mpi`` by adjusting the number 0706 of processors (:varlink:`nPx`, :varlink:`nPy`) according to «NUMBER_OF_PROCS» 0707 (see :numref:`testreport_utility`, ``testreport -MPI``); then it is 9061e4d211 Jean*0708 linked to :filelink:`SIZE.h <model/inc/SIZE.h>` (``ln -s SIZE.h.mpi SIZE.h``) before building the MPI-executable. b843492ec3 Jeff*0709 1c8cebb321 Jeff*0710 directory «TESTDIR»/code_ad/ b843492ec3 Jeff*0711 Contains the test-experiment specific source code used to build the MITgcm executable (``mitgcmuv_ad``) for 0712 adjoint-test (using ``genmake2 -mods=../code_ad``). It can also contain specific source files with the suffix 0713 ``_mpi`` (see above). 0714 0715 directory «TESTDIR»/build/ 0716 Directory where :filelink:`testreport <verification/testreport>` 0717 will build the MITgcm executable for forward and adjoint tests. It is initially empty except in some cases 0718 will contain an experiment specific ``genmake_local`` file (see :numref:`genmake2_desc`). 0719 directory TESTDIR/input/ 0720 Contains the input and parameter files used to run the primary forward test of this test-experiment. 0721 0722 It can also contain specific parameter files with the suffix ``.mpi`` to be used in place of the corresponding file 9061e4d211 Jean*0723 (without suffix) for MPI tests, or with suffix ``.mth`` to be used for b843492ec3 Jeff*0724 multi-threaded tests (see :numref:`testreport_utility`). The presence or absence of 0725 ``eedata.mth`` determines whether or not a multi-threaded test on this test-experiment is 0726 performed or skipped, respectively. 0727 0728 To save disk space and reduce downloading time, multiple copies of the same input file are avoided by using a 0729 shell script ``prepare_run``. When such a script is found in ``TESTDIR/input/``, 0730 :filelink:`testreport <verification/testreport>` runs this script in 0731 directory ``TESTDIR/run/`` after linking all the input files from ``TESTDIR/input/``. 0732 1c8cebb321 Jeff*0733 directory «TESTDIR»/input_ad/ b843492ec3 Jeff*0734 Contains the input and parameter files used to run the primary adjoint test of this test-experiment. It can also 0735 contain specific parameter files with the suffix ``.mpi`` and shell script ``prepare_run`` as described above. 0736 1c8cebb321 Jeff*0737 directory «TESTDIR»/input.«OTHER»/ b843492ec3 Jeff*0738 Contains the input and parameter files used to run the secondary OTHER forward test of this test-experiment. 0739 It can also contain specific parameter files with suffix ``.mpi`` or ``.mth`` and shell script 0740 ``prepare_run`` (see above). 0741 0742 The presence or absence the file ``eedata.mth`` determines whether or not a secondary multi-threaded test on this 0743 test-experiment is performed or skipped. 0744 1c8cebb321 Jeff*0745 directory «TESTDIR»/input_ad.«OTHER»/ b843492ec3 Jeff*0746 Contains the input and parameter files used to run the secondary OTHER adjoint test of this test-experiment. It 0747 can also contain specific parameter files with the suffix ``.mpi`` and shell script ``prepare_run`` (see above). 0748 9061e4d211 Jean*0749 directory «TESTDIR»/results/ b843492ec3 Jeff*0750 Contains reference standard output used for test comparison. 0751 ``results/output.txt`` and ``results/output_adm.txt``, 0752 respectively, correspond to primary forward and adjoint test run on the reference a1cc1bfacb Jean*0753 platform (currently villon.mit.edu) on one processor (no MPI, single thread) using the b843492ec3 Jeff*0754 reference compiler (currently the `GNU Fortran compiler gfortran <https://gcc.gnu.org/fortran>`_). 0755 The presence of these output files determines 0756 whether or not :filelink:`testreport <verification/testreport>` 0757 is testing or skipping this test-experiment. Reference standard output for secondary tests 0758 (``results/output.«OTHER».txt`` or ``results/output_adm.«OTHER».txt``) are also expected here. 9061e4d211 Jean*0759 1c8cebb321 Jeff*0760 directory «TESTDIR»/run/ b843492ec3 Jeff*0761 Initially empty directory where :filelink:`testreport <verification/testreport>` 0762 will run the MITgcm executable for primary forward and adjoint tests. 0763 0764 Symbolic links (using command ``ln -s``) are made for input and parameter files 0765 (from ``../input/`` or from ``../input_ad/``) and for MITgcm executable (from 0766 ``../build/``) before the run proceeds. The sequence of links (function 0767 ``linkdata`` within shell script :filelink:`testreport <verification/testreport>`) 0768 for a forward test is: 0769 0770 - link and rename or remove links to special files with suffix ``.mpi`` or ``.mth`` from ``../input/`` 0771 - link files from ../input/ 0772 - execute ``../input/prepare_run`` (if it exists) 0773 0774 The sequence for an adjoint test is similar, with ``../input_ad/`` replacing ``../input/``. 0775 1c8cebb321 Jeff*0776 directory «TESTDIR»/tr_run.«OTHER»/ b843492ec3 Jeff*0777 Directory created by :filelink:`testreport <verification/testreport>` 0778 to run the MITgcm executable for secondary "OTHER" forward or adjoint tests. 0779 0780 The sequence of links for a forward secondary test is: 0781 0782 - link and rename or remove links to special files with suffix ``.mpi`` or ``.mth`` from ``../input.OTHER/`` 0783 - link files from ``../input.OTHER/`` 0784 - execute ``../input.OTHER/prepare_run`` (if it exists) 0785 - link files from ``../input/`` 0786 - execute ``../input/prepare_run`` (if it exists) 0787 0788 The sequence for an adjoint test is similar, with ``../input_ad.OTHER/`` 0789 and ``../input_ad/`` replacing ``../input.OTHER/`` and ``../input/``. 0790 0791 .. _testreport_utility: 0792 0793 The testreport utility 0794 ---------------------- 0795 0796 The shell script :filelink:`testreport <verification/testreport>`, which was written to work with 0797 :filelink:`genmake2 <tools/genmake2>`, can be used to build different versions of MITgcm code, 0798 run the various examples, and compare the output. 0799 On some systems, the :filelink:`testreport <verification/testreport>` 0800 script can be run with a command line as simple as: 0801 0802 :: 0803 0804 % cd verification 9061e4d211 Jean*0805 % ./testreport -optfile ../tools/build_options/linux_amd64_gfortran b843492ec3 Jeff*0806 0807 The :filelink:`testreport <verification/testreport>` script accepts a number of command-line options which can be listed using the 0808 ``-help`` option. The most important ones are: 0809 0810 ``-ieee`` (default) / ``-fast`` 0811 If allowed by the compiler (as defined in the specified optfile), use IEEE arithmetic (``genmake2 -ieee``). 0812 In contrast, ``-fast`` uses the optfile default for compiler flags. 0813 0814 ``-devel`` 0815 Use optfile development flags (assumes specified in optfile). 0816** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 818.
0817 ``-optfile «/PATH/FILENAME»`` (or ``-optfile â«/PATH/F1» «/PATH/F2» ...â``) 0818 This specifies a list of "options files" that will be passed to :filelink:`genmake2 <tools/genmake2>`. 0819 If multiple options files are used (for example, to test different compilers 0820 or different sets of options for the same compiler), then each options file will be used 0821 with each of the test directories. 0822** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 824.
0823 ``-tdir «TESTDIR»`` (or ``-tdir â«TDIR1» «TDIR2» ...â``) 0824 This option specifies the test directory or list of test directories that should be used. 0825 Each of these entries should exactly match (note: they are case sensitive!) the names of directories in 0826 :filelink:`verification`. If this option is omitted, then all directories that are 0827 properly formatted (that is, containing an input subdirectory and a ``results/output.txt`` 0828 file) will be used. 0829** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 831.
0830 ``-skipdir «TESTDIR»`` (or ``-skipdir â«TDIR1» «TDIR2» ...â``) 0831 This option specifies a test directory or list of test directories to skip. The default is to test **ALL** 0832 directories in :filelink:`verification`. 0833 0834 ``-MPI «NUMBER_OF_PROCS»`` (or ``-mpi``) 0835 If the necessary file ``«TESTDIR»/code/SIZE.h_mpi`` exists, then use it (and all 9061e4d211 Jean*0836 ``TESTDIR/code/*_mpi`` files) for an MPI-enabled run. The option 0837 ``-MPI`` followed by the maximum number of processors enables to b843492ec3 Jeff*0838 build and run each test-experiment using different numbers 0839 of MPI processors (specific number chosen by: 0840 multiple of nPx*nPy from ``«TESTDIR»/code/SIZE.h_mpi`` and not larger than 0841 «NUMBER_OF_PROCS»). The short option (``-mpi``) can only be used to 0842 build and run on 2 MPI processors (equivalent to ``-MPI 2``). 0843 0844 Note that the use of MPI typically requires a special command option (see "-command" below) to invoke the 9061e4d211 Jean*0845 MPI executable. b843492ec3 Jeff*0846** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 848.
0847 ``-command=â«SOME COMMANDS TO RUN»â`` 0848 For some tests, particularly MPI runs, a specific command might be needed to run the executable. 9061e4d211 Jean*0849 This option allows a more general command (or shell script) to be invoked. 0850 b843492ec3 Jeff*0851 The default here is for «SOME COMMANDS TO RUN» to be replaced by 0852 ``mpirun -np TR_NPROC mitgcmuv``. If on your system you require 0853 something other than ``mpirun``, you will need to use the option** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 855.
0854 and specify your computerâs syntax. Because the number of MPI processors 0855 varies according to each test-experiment, the keyword TR_NPROC 0856 will be replaced by its effective value, the actual number of MPI processors 0857 needed to run the current test-experiment. 0858 0859 ``-mth`` 0860 Compile with ``genmake2 -omp`` and run with multiple threads (using ``eedata.mth``). 0861 0862 ``-adm`` 0863 Compile and test the adjoint suite of verification runs using TAF. 0864 0865 ``-clean`` 0866 Clean out all files/progress from any previously executed :filelink:`testreport <verification/testreport>` runs. 0867 0868 ``-match «NUMBER»`` 0869 Set matching criteria to «NUMBER» of significant digits (default is 10 digits). 0870 0871 Additional :filelink:`testreport <verification/testreport>` options are available 0872 to pass options to :filelink:`genmake2 <tools/genmake2>` (called during :filelink:`testreport <verification/testreport>` execution) 0873 as well as additional options to skip specific steps of the 9061e4d211 Jean*0874 :filelink:`testreport <verification/testreport>` shell script. See b843492ec3 Jeff*0875 ``testreport -help`` for a detailed list. 0876 0877 In the :filelink:`verification/` directory, the :filelink:`testreport <verification/testreport>` script will create an output 0878 directory «tr_NAME_DATE_N», with your computer hostname substituted for 0879 NAME, the current date for DATE, followed by a suffix number N to distinguish 0880 from previous :filelink:`testreport <verification/testreport>` 0881 output directories. Unless you specify otherwise using the ``-tdir`` or ``-skipdir`` options described above, 9061e4d211 Jean*0882 all sub-directories (i.e., TESTDIR experiments) in :filelink:`verification` will be tested. b843492ec3 Jeff*0883 :filelink:`testreport <verification/testreport>` writes progress to the screen (stdout) and 0884 reports into the «tr_NAME_DATE_N/TESTDIR» sub-directories as it runs. In particular, 0885 one can find, in each TESTDIR subdirectory, a 0886 ``summary.txt`` file in addition to log and/or error file(s) (depending how the run failed, if this occurred). 9061e4d211 Jean*0887 ``summary.txt`` contains information about the run and a comparison of the current** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 889.
0888 output with âreference outputâ (see :ref:`below <reference_output>` for information on how this reference output is generated). b843492ec3 Jeff*0889 The test comparison involves several output model variables. By default, for a forward test, these are the 2D 0890 solver initial residual ``cg2d_init_res`` and 3D state variables 0891 (T, S, U, V) from :filelink:`pkg/monitor` output; by default 0892 for an adjoint test, the cost-function and gradient-check. However, some test-experiments 0893 use some package-specific variables from :filelink:`pkg/monitor` according to the file 0894 ``«TESTDIR»/input[_ad][.«OTHER»]/tr_checklist`` specification. Note that at this time, 0895 the only variables that are compared by :filelink:`testreport <verification/testreport>` 0896 are those dumped in standard output via :filelink:`pkg/monitor`, not output produced 0897 by :filelink:`pkg/diagnostics`. Monitor output produced from **ALL** run time steps are compared 0898 to assess significant digit match; the worst match is reported. 0899 At the end of the testing process, a composite 0900 ``summary.txt`` file is generated in the top «tr_NAME_DATE_N» directory as a compact, combined version of the ``summary.txt`` 0901 files located in all TESTDIR sub-directories 0902 (a slightly more condensed version of this information is also written to file ``tr_out.txt`` in the top :filelink:`verification/` directory; 0903 note this file is overwritten upon subsequent :filelink:`testreport <verification/testreport>` runs). 0904 :numref:`testreport_output` shows an excerpt from the composite ``summary.txt``, created by running the full testreport suite (in the example here, on a linux cluster, using gfortran): 0905 0906 .. figure:: figs/testreport_output.* 0907 :width: 100% 0908 :align: center 0909 :alt: output text from summary.txt 0910 :name: testreport_output 0911 0912 Example output from testreport ``summary.txt`` 0913 0914 The four columns on the left are build/run results (successful=Y, unsuccessful=N). Explanation of these columns is as follows: 0915 0916 - Gen2: did genmake2 build the makefile for this experiment without error? 0917 - Dpnd: did the ``make depend`` for this experiment complete without error? 0918 - Make: did the ``make`` successfully generate a ``mitgcmuv`` executable for this experiment? 0919 - Run: did execution of this experiment startup and complete successfully? 0920 0921 The next sets of columns shows the number of significant digits matched from the monitor** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 923.
0922 output âcg2dâ, âminâ, âmaxâ, âmeanâ, and âs dâ (standard deviation) for variables T, S, U, and V (see column headings), as compared with the reference output. 0923 NOTE: these column heading labels are for the default list of variables, even if different variables are specified in a ``tr_checklist`` file 0924 (for reference, the list of actual variables tested for a specific TESTDIR experiment is output near the end of the file ``summary.txt`` 0925 appearing in the specific TESTDIR experiment directory).** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 927.
0926 For some experiments, additional variables are tested, as shown in âPTR 01â, âPTR 02â sets of columns; 0927 :filelink:`testreport <verification/testreport>` will detect if tracers are active 0928 in a given experiment and check digit match on their concentration values. 0929 A match to near-full machine precision is 15-16 digits; this generally will occur when a similar type of computer, 0930 similar operating system, and similar version of Fortran compiler are used for the test. Otherwise, different round-off can occur, 0931 and due to the chaotic nature of ocean and climate models, fewer digits (typically, 10-13 digits) are matched. A match of 22 digits generally is 9061e4d211 Jean*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 933.
0932 due to output being exactly 0.0. In some experiments, some variables may not be used or meaningful, which causes the â0â and â4â match results b843492ec3 Jeff*0933 in several of the adjustment experiments above. 0934 0935 While the significant digit match for many variables is tested and displayed in ``summary.txt``, 0936 only one of these is used to assess pass/fail (output to the right of the match test results) -- the number bracketed by ``>`` and ``<``.** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 938.
0937 For example, see above for experiment :filelink:`advect_cs <verification/advect_cs>` the pass/fail test occurs on variable âT: s dâ 0938 (i.e., standard deviation of potential temperature), the first variable in the list specified in 0939 :filelink:`verification/advect_cs/input/tr_checklist`. By default (i.e., if no file ``tr_checklist`` is present), 0940 pass/fail is assessed on the cg2d monitor output. 0941 See the :filelink:`testreport <verification/testreport>` script for a list of 0942 permissible variables to test and a guide to their abbreviations. See ``tr_checklist`` files in the input subdirectories of several TESTDIR 9061e4d211 Jean*0943 experiments (e.g., :filelink:`verification/advect_xz/input/tr_checklist`) for examples of syntax (note, a ``+`` after a variable in a ``tr_checklist file`` is shorthand to compare the b843492ec3 Jeff*0944 mean, minimum, maximum, and standard deviation for the variable). 0945 0946 .. _reference_output: 0947 0948 Reference Output 0949 ~~~~~~~~~~~~~~~~ 0950 a1cc1bfacb Jean*0951 Reference output is currently generated using the linux server ``villon.mit.edu`` which employs an Intel Haswell processor running Ubuntu 18.04.3 LTS. b843492ec3 Jeff*0952 For each verification experiment in the MITgcm repository, this reference output is stored in the file ``«TESTDIR»/results/output.txt``, 0953 which is the standard output generated by running :filelink:`testreport <verification/testreport>` a1cc1bfacb Jean*0954 (using a single process) on ``villon.mit.edu`` using the gfortran (`GNU Fortran <https://gcc.gnu.org/fortran>`_) compiler version 7.4.0. b843492ec3 Jeff*0955 0956 Using a different gfortran version (or a different Fortran compiler entirely), and/or running with MPI, 0957 a different operating system, or a different processor (cpu) type will generally result in output that differs to machine precision. 0958 The greater the number of such differences between your platform and this reference platform, typically the fewer digits of matching output precision. 0959 0960 The do_tst_2+2 utility 0961 ---------------------- 0962 0963 The shell script :filelink:`tools/do_tst_2+2` can be used to check the accuracy of the restart procedure. 9061e4d211 Jean*0964 For each experiment that has been run through testreport, b843492ec3 Jeff*0965 :filelink:`do_tst_2+2 <tools/do_tst_2+2>` executes three additional short runs using the tools/tst2+2 script. 0966 The first run makes use of the pickup files output 0967 from the run executed by :filelink:`testreport <verification/testreport>` to restart and run 0968 for four time steps, writing pickup files upon completion. The second run 0969 is similar except only two time steps are executed, writing pickup files. 0970 The third run restarts from the end of the second run, executing two additional time steps, 0971 writing pickup files upon completion. 9061e4d211 Jean*0972 In order to successfully pass :filelink:`do_tst_2+2 <tools/do_tst_2+2>`, not only must all three runs execute and complete successfully, b843492ec3 Jeff*0973 but the pickups generated at the end the first run must be identical to the pickup files from the end of the third run. 0974 Note that a prerequisite to running :filelink:`do_tst_2+2 <tools/do_tst_2+2>` 0975 is running :filelink:`testreport <verification/testreport>`, both to build the executables used by :filelink:`do_tst_2+2 <tools/do_tst_2+2>`, 0976 and to generate the pickup files from which :filelink:`do_tst_2+2 <tools/do_tst_2+2>` begins execution. 0977 0978 The :filelink:`tools/do_tst_2+2` script should be called from the :filelink:`verification/` directory, e.g.: 0979 0980 :: 0981 0982 % cd verification 0983 % ../tools/do_tst_2+2 0984 0985 The :filelink:`do_tst_2+2 <tools/do_tst_2+2>` script accepts a number of command-line options which can be listed using the 0986 ``-help`` option. The most important ones are: 0987 0988 ``-t «TESTDIR»`` 0989 Similar to :filelink:`testreport <verification/testreport>` option ``-tdir``, specifies the test directory or list of test directories that should be used. 0990 If omitted, the test is attempted in all sub-directories. 0991 0992 ``-skd «TESTDIR»`` 0993 Similar to :filelink:`testreport <verification/testreport>` option ``-skipdir``, specifies a test directory or list of test directories to skip. 0994 0995 ``-mpi`` 0996 Run the tests using MPI; requires the prerequisite :filelink:`testreport <verification/testreport>` 0997 run to have been executed with the ``-mpi`` or ``-MPI «NUMBER_OF_PROCS»`` flag. 0998 No argument is necessary, as the :filelink:`do_tst_2+2 <tools/do_tst_2+2>` script will determine the 0999 correct number of processes to use for your executable. 1000 1001 ``-clean`` 1002 Clean up any output generated from the :filelink:`do_tst_2+2 <tools/do_tst_2+2>`. 1003 This step is necessary if one wants to do additional :filelink:`testreport <verification/testreport>` runs 1004 from these directories. 1005 1006 Upon completion, :filelink:`do_tst_2+2 <tools/do_tst_2+2>` will generate a file ``tst_2+2_out.txt`` 1007 in the :filelink:`verification/` directory which summarizes the results. 1008 The top half of the file includes information from the composite ``summary.txt`` file from the prerequisite :filelink:`testreport <verification/testreport>` run. 1009 In the bottom half, new results from each verification experiment are given: 1010 each line starts with four Y/N indicators indicating if pickups from 1011 the :filelink:`testreport <verification/testreport>` run were available, 1012 and whether runs 1, 2 and 3, completely successfully, respectively, 1013 followed by a pass or fail from the output pickup file comparison test, followed by the TESTDIR experiment name. 1014 In each ``«TESTDIR»/run`` subdirectory 1015 :filelink:`do_tst_2+2 <tools/do_tst_2+2>` also creates a log file ``tst_2+2_out.log`` which contains additional information. 1016 During :filelink:`do_tst_2+2 <tools/do_tst_2+2>` execution a separate directory of summary information, 1017 including log files for all failed tests, is created in an output directory «rs_NAME_DATE_N» 1018 similar to the syntax for the :filelink:`testreport <verification/testreport>` output directory name. 1019 Note however this directory is deleted by default 1020 upon :filelink:`do_tst_2+2 <tools/do_tst_2+2>` completion, but can be saved 1021 by adding the :filelink:`do_tst_2+2 <tools/do_tst_2+2>` command line option ``-a NONE``. 1022 1023 Daily Testing of MITgcm 1024 ----------------------- 1025 1026 On a daily basis, MITgcm runs a full suite of :filelink:`testreport <verification/testreport>` 1027 (i.e., forward and adjoint runs, single process, single-threaded and mpi) on an array of different 1028 clusters, running using different operating systems, testing several different Fortran compilers. a1cc1bfacb Jean*1029 The reference machine ``villon.mit.edu`` is one of such daily test machines. b843492ec3 Jeff*1030 When changes in output occur from previous runs, even if as minor as changes 003d2d851e Jeff*1031 in numeric output to machine precision, MITgcm head developers are automatically notified. b843492ec3 Jeff*1032 9061e4d211 Jean*1033 Links to summary results from the daily testing are posted at http://mitgcm.org/public/testing.html. b843492ec3 Jeff*1034 1035 Required Testing for MITgcm Code Contributors 1036 --------------------------------------------- 1037 1038 Using testreport to check your new code 1039 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1040 1041 Before submitting your pull request for approval, if you have made any changes to MITgcm code, however trivial, you **MUST** complete the following: 1042 1043 - Run :filelink:`testreport <verification/testreport>` (on all experiments) on an unmodified master branch of MITgcm. We suggest using the ``-devel`` option 1044 and gfortran (typically installed in most linux environments) although neither is strictly necessary for this test. 1045 Depending how different your platform 1046 is from our reference machine setup, typically most tests will pass but some match tests may fail; it is possible one or more experiments might not even 1047 build or run successfully. But even if there are multiple experiment fails or unsuccessful builds or runs, do not despair, the purpose at this 1048 stage is simply to generate a reference report on your local platform using the master code. 1049 It may take one or more hours for :filelink:`testreport <verification/testreport>` to complete. 1050 1051 - Save a copy of this summary output from running :filelink:`testreport <verification/testreport>` on the mastrer branch: from the verification 1052 directory, type ``cp tr_out.txt tr_out_master.txt``. The file ``tr_out.txt`` is simply a condensed version of the 1053 composite ``summary.txt`` file located in the «tr_NAME_DATE_N» directory. Note we are not making this file "git-aware", 1054 as we have no desire to check this into the repo, 1055 so we are using an old-fashioned copy to save the output here for later comparison. 1056 1057 - Switch to your pull request branch, and repeat the :filelink:`testreport <verification/testreport>` sequence using the same options. 1058 9061e4d211 Jean*1059 - From the verification directory, type ``diff tr_out_master.txt tr_out.txt`` b843492ec3 Jeff*1060 which will report any differences in :filelink:`testreport <verification/testreport>` output from the above tests. 1061 If no differences occur (other than timestamp-related), see below if you are required 1062 to do a :filelink:`do_tst_2+2 <tools/do_tst_2+2>` test; otherwise, you 1063 are clear for submitting your pull request. 1064 1065 Differences might occur due to one or more of the following reasons: 1066 1067 - Your modified code no longer builds properly in one or more experiments. This is likely due to a Fortran syntax error; examine output and log files 1068 in the failed experiment TESTDIR to identify and fix the problem. 1069 1070 - The run in the modified code branch terminates due to a numerical exception error. This too requires further investigation into the cause of the error, 1071 and a remedy, before the pull request should be submitted. 1072 1073 - You have made changes which require changes to input parameters 9061e4d211 Jean*1074 (e.g., renaming a namelist parameter, changing the units or function of an input parameter, etc.) b843492ec3 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1076.
1075 This by definition is a âbreaking changeâ, which must be noted when completing the PR template -- but should not deter you from 003d2d851e Jeff*1076 submitting your PR. Ultimately, you and the MITgcm head developers will likely have to make changes to one or more verification experiments, but as a first b843492ec3 Jeff*1077 step we will want to review your PR. 1078** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1080.
1079 - You have made algorithmic changes which change model output in some or all setups; this too is a âbreaking changeâ that should be noted in 003d2d851e Jeff*1080 the PR template. As usual recourse, if the PR is accepted, the head developers will re-generate reference output and push to the affected b843492ec3 Jeff*1081 ``«TESTDIR»/results/`` directories when the PR is merged. 9061e4d211 Jean*1082 b843492ec3 Jeff*1083 Most typically, running testreport using a single process is a sufficient test. However, any code changes which call MITgcm 1084 routines (such as :filelink:`eesupp/src/global_sum.F`) employing low-level MPI-directives 1085 should run :filelink:`testreport <verification/testreport>` with the ``-mpi`` option enabled. 1086 1087 Using do_tst_2+2 to check your new code 1088 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1089 1090 If you make any kind of algorithmic change to the code, or modify anything related to generating or reading pickup files, 1091 you are also required to also complete a :filelink:`do_tst_2+2 <tools/do_tst_2+2>`. Again, run the test on both the unmodified master branch and your 1092 pull request branch (after you have run :filelink:`testreport <verification/testreport>` on both branches). 1093 Verify that the output ``tst_2+2_out.txt`` file is identical between branches, similar to the above procedure for the file ``tr_out.txt``. 1094 If the files differ, attempt to identify and fix what is causing the problem. 1095 f8d284a60d Jeff*1096 Automatic testing with GitHub Actions 1097 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ aac9606f76 Jeff*1098 b843492ec3 Jeff*1099 Once your PR is submitted onto GitHub, the continuous integration service f8d284a60d Jeff*1100 `GitHub Actions <https://docs.github.com/en/actions>`_ runs additional tests on your PR submission. b843492ec3 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1102.
1101 On the âPull requestâ tab in GitHub (https://github.com/MITgcm/MITgcm/pulls), find your pull request; initially you will see a yellow circle 1102 to the right of your PR title, indicating testing in progress. Eventually this will change to a green checkmark (pass) or a red X (fail).** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1104.
1103 If you get a red X, click the X and then click on âDetailsâ to list specifics tests that failed; these can be clicked to produce a screenshot 1104 with error messages. 1105 f8d284a60d Jeff*1106 Note that `GitHub Actions <https://docs.github.com/en/actions>`_ builds documentation (both html and latex) in addition to code testing, so if you have b843492ec3 Jeff*1107 introduced syntax errors into the documentation files, 1108 these will be flagged at this stage. Follow the same procedure as above to identify the error messages so the problem(s) can be fixed. Make any 1109 appropriate edits to your pull request, re-``git add`` and re-``git commit`` any newly modified files, re-``git push``. Anytime changes are pushed to the PR, f8d284a60d Jeff*1110 `GitHub Actions <https://docs.github.com/en/actions>`_ will re-run its tests. b843492ec3 Jeff*1111 003d2d851e Jeff*1112 The MITgcm head developers will not review your PR until all `GitHub Actions <https://docs.github.com/en/actions>`_ tests pass. aac9606f76 Jeff*1113 1114 .. _contrib_manual: 1115 1116 Contributing to the manual 1117 ========================== 1118 af61fa61c7 Jeff*1119 Whether you are simply correcting typos or describing undocumented packages, 1120 we welcome all contributions to the manual. The following information will 1121 help you make sure that your contribution is consistent with the style of 1122 the MITgcm documentation. (We know that not all of the current documentation 1123 follows these guidelines - we're working on it) 1124 1125 The manual is written in **rst** format, which is short for ReStructuredText 1126 directives. rst offers many wonderful features: it automatically does much of 1127 the formatting for you, it is reasonably well documented on the web (e.g., 1128 primers available `here <http://www.sphinx-doc.org/en/stable/rest.html>`__ and 1129 `here <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`__), it 1130 can accept raw latex syntax and track equation labelling for you, in addition 1131 to numerous other useful features. On the down side however, it can be very 1132 fussy about formatting, requiring exact spacing and indenting, and seemingly 1133 innocuous things such as blank spaces at ends of lines can wreak havoc. We 1134 suggest looking at the existing rst files in the manual to see exactly how 1135 something is formatted, along with the syntax guidelines specified in this 1136 section, prior to writing and formatting your own manual text. 1137 1138 The manual can be viewed either of two ways: interactively (i.e., web-based), 1139 as hosted by read-the-docs (https://readthedocs.org/), 9061e4d211 Jean*1140 requiring an html format build, or downloaded as a pdf file. af61fa61c7 Jeff*1141 When you have completed your documentation edits, you should double 1142 check both versions are to your satisfaction, particularly noting that 1143 figure sizing and placement may be rendered differently in the pdf build. 81ac464415 gael*1144 See :ref:`building_the_manual` for detail. aac9606f76 Jeff*1145 1146 Section headings 1147 ---------------- 1148 1149 - Chapter headings - these are the main headings with integer numbers - underlined with ``****`` 1150 - section headings - headings with number format X.Y - underlined with ``====`` af61fa61c7 Jeff*1151 - Subsection headings - headings with number format X.Y.Z - underlined with ``----`` 1152 - Subsubsection headings - headings with number format X.Y.Z.A - underlined with ``~~~~`` 1153 - Paragraph headings - headings with no numbers - underlined with ``^^^^`` aac9606f76 Jeff*1154 1155 N.B. all underlinings should be the same length as the heading. If they are too short an error will be produced. 1156 1157 .. _referencing: 1158 1159 Internal document references 1160 ---------------------------- 1161 af61fa61c7 Jeff*1162 rst allows internal referencing of figures, tables, section headings, and 1163 equations, i.e. clickable links that bring the reader to the respective 1164 figure etc. in the manual. aac9606f76 Jeff*1165 To be referenced, a unique label is required. To reference figures, tables, or section headings by number, af61fa61c7 Jeff*1166 the rst (inline) directive is ``:numref:`«LABELNAME»```. For example, 1167 this syntax would write out ``Figure XX`` on a line (assuming «LABELNAME» referred to a figure), aac9606f76 Jeff*1168 and when clicked, would relocate your position af61fa61c7 Jeff*1169 in the manual to figure XX. Section headings can also be referenced 9061e4d211 Jean*1170 so that the name is written out instead of the section number, instead using this af61fa61c7 Jeff*1171 directive ``:ref:`«LABELNAME»```. aac9606f76 Jeff*1172 af61fa61c7 Jeff*1173 Equation references have a slightly different inline syntax: ``:eq:`«LABELNAME»``` 9061e4d211 Jean*1174 will produce a clickable equation number reference, surrounded by parentheses. aac9606f76 Jeff*1175 af61fa61c7 Jeff*1176 For instructions how to assign a label to tables and figures, see 1177 :ref:`below <how_to_figures>`. To label a section heading, 1178 labels go above the section heading they refer to, with the format ``.. _«LABELNAME»:``. 1179 Note the necessary leading underscore. You can also place a clickable 1180 link to *any* spot in the text (e.g., mid-section), 1181 using this same syntax to make the label, using the syntax 1182 ``:ref:`«SOME TEXT TO CLICK ON» <«LABELNAME»>``` for the link. aac9606f76 Jeff*1183 b843492ec3 Jeff*1184 Citations 1185 --------- 1186** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1188.
1187 In the text, references should be given using the standard âAuthor(s) (Year)â shorthand followed by a link 1188 to the full reference in the manual bibliography. This link is accomplished using the syntax** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1190.
1189 ``:cite:`«BIB_REFERENCE»```; this will produce clickable text, usually some variation on the authorsâ initials or names, surrounded by brackets. 1190 1191 Full references are specified in the file :filelink:`doc/manual_references.bib` 1192 using standard `BibTeX <http://www.bibtex.org>`_ format. 1193 Even if unfamiliar with `BibTeX <http://www.bibtex.org>`_, it is relatively easy 1194 to add a new reference by simply examining other entries. Furthermore, most 1195 publishers provide a means to download BibTex formatted references directly from their website. 1196 Note this file is in approximate alphabetic order by author name. 1197 For all new references added to the manual, please include a `DOI <https://www.doi.org>`_ or 1198 a URL in addition to journal name, volume and other 1199 standard reference infomation. An example JGR journal article reference is** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1201.
1200 reproduced below; note the «BIB_REFERENCE» here is âbryan:79â so the syntax in the rst file format would be ``âBryan and Lewis (1979) :cite:`bryan:79```, 1201 which will appear in the manual as Bryan and Lewis (1979) :cite:`bryan:79`. 1202 1203 | @Article{bryan:79, 1204 | author = {Bryan, K. and L.J. Lewis}, 1205 | title = {A water mass model of the world ocean}, 1206 | journal = jgr, 1207 | volume = 84, 1208 | number = {C5}, 1209 | pages = {2503--2517}, 1210 | doi = {10.1029/JC084iC05p02503}, 1211 | year = 1979, 1212 | } 1213 aac9606f76 Jeff*1214 Other embedded links 1215 -------------------- 1216 af61fa61c7 Jeff*1217 **Hyperlinks:** to reference a (clickable) URL, simply enter the full URL. 1218 If you want to have a different, aac9606f76 Jeff*1219 clickable text link instead of displaying the full URL, the syntax af61fa61c7 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1221.
1220 is ```«CLICKABLE TEXT» <«URL»>`_`` (the â<â and â>â are literal characters, 9061e4d211 Jean*1221 and note the trailing underscore). 081ebf5000 Oliv*1222 For this kind of link, the clickable text has to be unique for each URL. If af61fa61c7 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1224.
1223 you would like to use non-unique text (like âclick hereâ), you should use 081ebf5000 Oliv*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1225.
1224 an âanonymous referenceâ with a double trailing underscore: af61fa61c7 Jeff*1225 ```«CLICKABLE TEXT» <«URL»>`__``. 1226 1227 **File references:** to create a link to pull up MITgcm code (or any file in the repo) 1228 in a code browser window, the syntax is ``:filelink:`«PATH/FILENAME»```. 1229 If you want to have a different text link to click on (e.g., say you** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1231.
1230 didnât want to display the full path), the syntax is 1231 ``:filelink:`«CLICKABLE TEXT» <«PATH/FILENAME»>```** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1233.
1232 (again, the â<â and â>â are literal characters). The top 1233 directory here is https://github.com/MITgcm/MITgcm , 1234 so if for example you wanted to pop open the file 1235 :filelink:`dynamics.F <model/src/dynamics.F>` 1236 from the main model source directory, you would specify 1237 ``model/src/dynamics.F`` in place of «PATH/FILENAME». 1238 1239 **Variable references:** to create a link to bring up a webpage 1240 displaying all MITgcm repo references to a particular variable 1241 name (for this purpose we are using the LXR Cross Referencer), 1242 the syntax is ``:varlink:`«NAME_OF_VARIABLE»```. This will work 1243 on CPP options as well as FORTRAN identifiers (e.g., common block 1244 names, subroutine names). aac9606f76 Jeff*1245 1246 .. _symbolic_notation: 1247 1248 Symbolic Notation 1249 ----------------- 1250 af61fa61c7 Jeff*1251 Inline math is done with ``:math:`«LATEX_HERE»``` aac9606f76 Jeff*1252 1253 Separate equations, which will be typeset on their own lines, are produced with:: 1254 1255 .. math:: af61fa61c7 Jeff*1256 «LATEX_HERE» 1257 :label: «EQN_LABEL_HERE» aac9606f76 Jeff*1258 af61fa61c7 Jeff*1259 Labelled separate equations are assigned an equation number, which may be 1260 referenced elsewhere in the document (see :numref:`referencing`). Omitting the ``:label:`` above aac9606f76 Jeff*1261 will still produce an equation on its own line, except without an equation label. af61fa61c7 Jeff*1262 Note that using latex formatting ``\begin{aligned}`` ... ``\end{aligned}`` 1263 across multiple lines of equations will not work in conjunction with unique 1264 equation labels for each separate line 1265 (any embedded formatting ``&`` characters will cause errors too). Latex alignment 1266 will work however if you assign a single label for the multiple lines of equations. 1267** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1269.
1268 There is a software tool âuniversal document converterâ named `pandoc <https://pandoc.org/>`_ 1269 that we have found helpful in converting raw latex documents 1270 into rst format. To convert a ``.tex`` file into ``.rst``, from a terminal window type: 1271 1272 :: 1273 1274 % pandoc -f latex -t rst -o «OUTPUT_FILENAME».rst «INPUT_FILENAME».tex 1275 1276 Additional conversion options are available, for example if you have your equations or text in another format; 1277 see the `pandoc documentation <https://pandoc.org/MANUAL.html>`_. 1278 1279 Note however we have found that a fair amount of clean-up is still 1280 required after conversion, particularly regarding 1281 latex equations/labels (pandoc has the unfortunate tendency to add 1282 extra spaces, sometimes confusing the rst ``:math:`` directive, other 1283 times creating issues with indentation). 1284 aac9606f76 Jeff*1285 .. _how_to_figures: 1286 1287 Figures 1288 ------- 1289 1290 The syntax to insert a figure is as follows:: 1291 af61fa61c7 Jeff*1292 .. figure:: «PATHNAME/FILENAME».* aac9606f76 Jeff*1293 :width: 80% 1294 :align: center af61fa61c7 Jeff*1295 :alt: «TEXT DESCRIPTION OF FIGURE HERE» 1296 :name: «MY_FIGURE_NAME» aac9606f76 Jeff*1297 1298 The figure caption goes here as a single line of text. 1299 1300 ``figure::``: The figure file is located in subdirectory ``pathname`` above; in practice, we have located figure files in subdirectories ``figs`` 1301 off each manual chapter subdirectory. af61fa61c7 Jeff*1302 The wild-card ``*`` is used here so that different file formats can be used in the build process. 9061e4d211 Jean*1303 For vector graphic images, save a ``pdf`` for the pdf build plus a ``svg`` file for the html build. af61fa61c7 Jeff*1304 For bitmapped images, ``gif``, ``png``, or ``jpeg`` formats can be used for both builds, 1305 no wild-card necessary, just substitute the actual extension 052e3563d8 Oliv*1306 (see `here <http://www.sphinx-doc.org/en/stable/builders.html>`__ for more info af61fa61c7 Jeff*1307 on compatible formats). [Note: A repository for figure source .eps needs to be created] aac9606f76 Jeff*1308 1309 ``:width:``: used to scale the size of the figure, here specified as 80% scaling factor 1310 (check sizing in both the pdf and html builds, as you may need to adjust the figure size within the pdf file independently). 1311 1312 ``:align:``: can be right, center, or left. 1313 af61fa61c7 Jeff*1314 ``:name:`` use this name when you refer to the figure in the text, i.e. ``:numref:`«MY_FIGURE_NAME»```. aac9606f76 Jeff*1315 1316 Note the indentation and line spacing employed above. 1317 1318 Tables 1319 ------ 1320 1321 There are two syntaxes for tables in reStructuredText. Grid tables are more flexible but cumbersome to create. Simple 1322 tables are easy to create but limited (no row spans, etc.). The raw rst syntax is shown first, then the output. 1323 1324 Grid Table Example: 1325 1326 :: 1327 1328 +------------+------------+-----------+ 1329 | Header 1 | Header 2 | Header 3 | 1330 +============+============+===========+ 1331 | body row 1 | column 2 | column 3 | 1332 +------------+------------+-----------+ 1333 | body row 2 | Cells may span columns.| 1334 +------------+------------+-----------+ 1335 | body row 3 | Cells may | - Cells | 1336 +------------+ span rows. | - contain | 1337 | body row 4 | | - blocks. | 1338 +------------+------------+-----------+ 1339 1340 +------------+------------+-----------+ 1341 | Header 1 | Header 2 | Header 3 | 1342 +============+============+===========+ 1343 | body row 1 | column 2 | column 3 | 1344 +------------+------------+-----------+ 1345 | body row 2 | Cells may span columns.| 1346 +------------+------------+-----------+ 1347 | body row 3 | Cells may | - Cells | 1348 +------------+ span rows. | - contain | 1349 | body row 4 | | - blocks. | 1350 +------------+------------+-----------+ 1351 1352 Simple Table Example: 1353 1354 :: 1355 9061e4d211 Jean*1356 ===== ===== ====== 1357 Inputs Output 1358 ------------ ------ 1359 A B A or B 1360 ===== ===== ====== 1361 False False False 1362 True False True 1363 False True True 1364 True True True 1365 ===== ===== ====== aac9606f76 Jeff*1366 1367 ===== ===== ====== 1368 Inputs Output 1369 ------------ ------ 1370 A B A or B 1371 ===== ===== ====== 1372 False False False 1373 True False True 1374 False True True 1375 True True True 1376 ===== ===== ====== 1377 1378 Note that the spacing of your tables in your ``.rst`` file(s) will not match the generated output; rather, 1379 when you build the final output, the rst builder (Sphinx) will determine how wide the columns need to be and space them appropriately. 1380 1381 Other text blocks 1382 ----------------- 1383 af61fa61c7 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1385.
1384 Conventionally, we have used the rst âinline literalâ syntax around any literal computer text (commands, labels, literal computer syntax etc.) 1385 Surrounding text with double back-quotes `````` results in output html ``like this``. 1386 aac9606f76 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1388.
1387 To set several lines apart in an whitespace box, e.g. useful for showing lines in from a terminal session, rst uses ``::`` to set off a âliteral blockâ. 1388 For example:: 1389 1390 :: 1391 1392 % unix_command_foo 9061e4d211 Jean*1393 % unix_command_fum aac9606f76 Jeff*1394 af61fa61c7 Jeff*1395 (note the ``::`` would not appear in the output html or pdf) A splashier way to outline a block, including a box label, aac9606f76 Jeff*** Warning **
Wide character in print at /usr/local/share/lxr/source line 1030, <$git> line 1397.
1396 is to employ what is termed in rst as an âadmonition blockâ. 9061e4d211 Jean*1397 In the manual these are used to show calling trees and for describing subroutine inputs and outputs. An example of aac9606f76 Jeff*1398 a subroutine input/output block is as follows: 1399 1400 .. admonition:: This is an admonition block showing subroutine in/out syntax 1401 :class: note 1402 1403 | .. admonition:: :filelink:`SUBROUTINE_NAME </model/src/subroutine_name.F>` 1404 | :class: note 9061e4d211 Jean*1405 | aac9606f76 Jeff*1406 | | :math:`var1` : **VAR1** ( :filelink:`WHERE_VAR1_DEFINED.h </model/inc/where_var1_defined.h>`) 1407 | | :math:`var2` : **VAR1** ( :filelink:`WHERE_VAR2_DEFINED.h </model/inc/where_var2_defined.h>` ) 1408 | | :math:`var3` : **VAR1** ( :filelink:`WHERE_VAR3_DEFINED.h </model/inc/where_var3_defined.h>` ) 1409 1410 An example of a subroutine in/out admonition box in the documentation is :ref:`here <correction_step_sr_in-out>`. 1411 1412 An example of a calling tree in the documentation is :ref:`here <call-tree-press-meth>`. 1413 9061e4d211 Jean*1414 To show text from a separate file (e.g., to show lines of code, show comments from a Fortran file, show a parameter file etc.), 09f3e09bee Jeff*1415 use the ``literalinclude`` directive. Example usage is shown here: 77c2f53e75 Timo*1416 1417 :: 1418 09f3e09bee Jeff*1419 .. literalinclude:: «FILE_TO_SHOW» 77c2f53e75 Timo*1420 :start-at: String indicating where to start grabbing text 1421 :end-at: String indicating where to stop grabbing text 1422 09f3e09bee Jeff*1423 Unlike the ``:filelink:`` and ``:varlink:`` directives, which assume a file path starting at the top of the MITgcm repository, 17956fce0f Ed D*1424 one must specify the path relative to the current directory of the file (for example, from the doc directory, it would require 09f3e09bee Jeff*1425 ``../../`` at the start of the file path to specify the base directory of the MITgcm repository). 9061e4d211 Jean*1426 Note one can instead use ``:start-after:`` and ``:end-before:`` to get text from the file between (not including) those lines. 1427 If one omits the ``start-at`` or ``start-after``, etc. options the whole file is shown. 17956fce0f Ed D*1428 More details for this directive can be found `here <http://www.sphinx-doc.org/en/stable/markup/code.html#directive-literalinclude>`__. 77c2f53e75 Timo*1429 Example usage in this documentation is :ref:`here <model_main_call_tree>`, 1430 where the lines to generate this are: 1431 1432 :: 1433 1434 .. literalinclude:: ../../model/src/the_model_main.F 1435 :start-at: C Invocation from WRAPPER level... 1436 :end-at: C | :: events. aac9606f76 Jeff*1437 1438 .. _subsec_manual_style_guide: 1439 1440 Other style conventions 1441 ----------------------- 1442 9061e4d211 Jean*1443 Units should be typeset in normal text, with a space between a numeric value and the unit, and exponents added with the ``:sup:`` command. aac9606f76 Jeff*1444 1445 :: 1446 1447 9.8 m/s\ :sup:`2` 1448 1449 will produce 9.8 m/s\ :sup:`2`. If the exponent is negative use two dashes ``--`` to make the minus sign sufficiently long. af61fa61c7 Jeff*1450 The backslash removes the space between the unit and the exponent. Similarly, for subscripts the command is ``:sub:``. aac9606f76 Jeff*1451 1452 Alternatively, latex ``:math:`` directives (see :ref:`above <symbolic_notation>`) may also be used to display units, using the ``\text{}`` syntax to display non-italic characters. 1453 ba0b047096 Mart*1454 Line length: as recommended in the 1455 `sphinx style guide <https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html#line-length>`_, 1456 lines of raw rst text should be kept to fewer than 80 characters (this 1457 restriction does not apply to tables, URLs, etc. where a line break might 1458 cause difficulty). aac9606f76 Jeff*1459 ba0b047096 Mart*1460 - Todo: determine how to break up sections into smaller files aac9606f76 Jeff*1461 81ac464415 gael*1462 .. _building_the_manual: 1463 aac9606f76 Jeff*1464 Building the manual 1465 ------------------- 1466 39fa6219cc Oliv*1467 Once you've made your changes to the manual, you should build it locally to 1468 verify that it works as expected. To do this you will need a working python 1469 installation with the following packages installed: aac9606f76 Jeff*1470 1471 - sphinx 1472 - sphinxcontrib-bibtex 7621b5d564 Oliv*1473 - sphinxcontrib-programoutput aac9606f76 Jeff*1474 - sphinx_rtd_theme 7621b5d564 Oliv*1475 - numpy aac9606f76 Jeff*1476 39fa6219cc Oliv*1477 These packages can be installed from the Python Package Index using pip. If you 1478 have an existing python installation using `Anaconda 1479 <https://www.anaconda.com/>`_ or one of its variants (e.g., `miniconda 1480 <https://docs.conda.io/en/latest/miniconda.html>`_), we recommend that you can 1481 create (and use) a clean environment with the required packages like this: ab961cc72f Jeff*1482 1483 :: 1484 1485 cd MITgcm 39fa6219cc Oliv*1486 conda create --name mitgcm_build_the_docs --channel conda-forge --file doc/requirements.txt 1487 conda activate mitgcm_build_the_docs 1488 [...] # do the work 1489 conda deactivate 1490 1491 If you don't yet have a python installation on your computer, we recommend 1492 following the `Anaconda installation procedure 1493 <https://www.anaconda.com/products/individual#Downloads>`_, then following the 1494 recipe above. You do not need to learn python to build the manual; just note 1495 you should type ``conda activate mitgcm_build_the_docs`` in a shell when 1496 starting up a manual editing session, and ``conda deactivate`` when you finish 1497 (also note you only need to perform the ``conda create ...`` step above when 1498 you **initially** follow the recipe). This will maintain a clean, separate 1499 python `virtual environment 1500 <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`_ 1501 for manual compilation and won't interfere with your python setup should you 1502 decide to learn python in the future. 1503 1504 Once these modules are installed you can build the html version of the manual 1505 by running ``make html`` in the ``doc`` directory. 1506 1507 To build the pdf version of the manual you will also need a working version of 1508 LaTeX that includes `several packages 1509 <http://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.latex.LaTeXBuilder>`_ 1510 that are not always found in minimal LaTeX installations. The command to build 1511 the pdf version is ``make latexpdf``, which should also be run in the ``doc`` 1512 directory. aac9606f76 Jeff*1513 1514 .. _sec_pullreq: 1515 1516 Reviewing pull requests 1517 ======================= 1518 b843492ec3 Jeff*1519 The only people with write access to the main repository are a small number of core MITgcm developers. They are the people that 7621b5d564 Oliv*1520 will eventually merge your pull requests. However, before your PR gets merged, 1521 it will undergo the automated testing on Travis-CI, and it will be assessed by the MITgcm community. aac9606f76 Jeff*1522 1523 **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. 1524 7621b5d564 Oliv*1525 The simplest way to examine a pull request is to `use GitHub <https://github.com/MITgcm/MITgcm/pulls>`_. You can look at changes made to files 1526 (GitHub will show you a standard linux ``diff`` for each file changed), read though commit messages, and/or peruse any comments 1527 the MITgcm community has made regarding this pull request. 1528 1529 If you are reviewing changes to the documentation, most likely you will also want to review the rendered manual in html format. 1530 While this is not available at GitHub, you can view html builds based on the pull request documentation 1531 using `this link <https://readthedocs.org/projects/mitgcm/builds>`_ at readthedocs.org. Here you will need to click on the appropriate 1532 pull request (as labeled by the pull request number), then click on "View docs" 1533 (not the green button near the top of the page, but the text in the middle of the page 1534 on the right side). 1535 1536 Finally, if you want to test pull requests locally (i.e., to compile or run the code), f8d284a60d Jeff*1537 you should download the pull request branch. You can do this either by cloning the branch from the pull request. 1538 If you are using ssh keys for command line authentication: 1539 1540 :: 1541 1542 git clone -b «THEIR_DEVELOPMENT_BRANCHNAME» git@github.com:«THEIR_GITHUB_USERNAME»/MITgcm.git 1543 1544 If you are using a personal access token for authentication: aac9606f76 Jeff*1545 1546 :: 9061e4d211 Jean*1547 af61fa61c7 Jeff*1548 git clone -b «THEIR_DEVELOPMENT_BRANCHNAME» https://github.com/«THEIR_GITHUB_USERNAME»/MITgcm.git aac9606f76 Jeff*1549 af61fa61c7 Jeff*1550 where «THEIR_GITHUB_USERNAME» is replaced by the username of the person proposing the pull request, f8d284a60d Jeff*1551 and «THEIR_DEVELOPMENT_BRANCHNAME» is the branch from their pull request. aac9606f76 Jeff*1552 af61fa61c7 Jeff*1553 Alternatively, you can add the repository of the user proposing the pull request as a remote to 1554 your existing local repository. Navigate to your local repository and type aac9606f76 Jeff*1555 1556 :: 9061e4d211 Jean*1557 af61fa61c7 Jeff*1558 git remote add «THEIR_GITHUB_USERNAME» https://github.com/«THEIR_GITHUB_USERNAME»/MITgcm.git aac9606f76 Jeff*1559 af61fa61c7 Jeff*1560 where «THEIR_GITHUB_USERNAME» is replaced by the user name of the person who has made the 1561 pull request. Then download their pull request changes aac9606f76 Jeff*1562 1563 :: 9061e4d211 Jean*1564 1565 git fetch «THEIR_GITHUB_USERNAME» aac9606f76 Jeff*1566 1567 and switch to the desired branch 1568 1569 :: 1570 9061e4d211 Jean*1571 git checkout --track «THEIR_GITHUB_USERNAME»/«THEIR_DEVELOPMENT_BRANCHNAME» aac9606f76 Jeff*1572 af61fa61c7 Jeff*1573 You now have a local copy of the code from the pull request and can run tests locally. 1574 If you have write access to the main repository you can push fixes or changes directly 1575 to the pull request. aac9606f76 Jeff*1576 af61fa61c7 Jeff*1577 None of these steps, apart from pushing fixes back to the pull request, require 1578 write access to either the main repository or the repository of the person proposing 1579 the pull request. This means that anyone can review pull requests. However, unless 1580 you are one of the core developers you won't be able to directly push changes. You 1581 will instead have to make a comment describing any problems you find.
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated from https://github.com/darwinproject/darwin3 by the 2.3.7-MITgcm-0.1 LXR engine. The LXR team |
|