|
|
| (2 intermediate revisions by one other user not shown) |
| Line 1: |
Line 1: |
| − | == Overview ==
| + | This content has been migrated to [https://geos-chem.readthedocs.io/en/latest/reference/CONTRIBUTING.html the '''Contributing guidelines''' page at <tt>geos-chem.readthedocs.io</tt>]. |
| − | | + | |
| − | The [http://acmg.seas.harvard.edu/geos/geos_steering_cmte.html GEOS-Chem Steering Committee (GCSC)] encourages updates to the GEOS-Chem model. Updates to the GEOS-Chem model benefit both the developer and [http://acmg.seas.harvard.edu/geos/geos_people.html the entire GEOS-Chem community]. The developer benefits through [http://acmg.seas.harvard.edu/geos/geos_credit_and_refs.html coauthorship and citations]. Priority development needs are identified at GEOS-Chem users' meetings with updates between meetings based on GCSC input through working groups.
| + | |
| − | | + | |
| − | When should you submit updates to the GEOS-Chem code? Bug fixes should be submitted as soon as possible and be given high priority. Code related to model developments should be submitted when it is mature (i.e. a paper has been submitted). Your working group chair can offer guidance on the timing of submitting code to the GCST.
| + | |
| − | | + | |
| − | The practical aspects of submitting updates to the [[GEOS-Chem Support Team]] are outlined [[#Guidelines|below]].
| + | |
| − | | + | |
| − | == Guidelines ==
| + | |
| − | | + | |
| − | # Contact your [http://acmg.seas.harvard.edu/geos/geos_working_groups.html Working Group] leaders to request that your changes be included in the standard code.
| + | |
| − | #*The GEOS-Chem Steering Committee will meet every three months and set the [[GEOS-Chem model development priorities]] (i.e. decide on the order in which updates will be added to GEOS-Chem).<br><br>
| + | |
| − | # Create or log into your [https://github.com/ GitHub] account.<br><br>
| + | |
| − | # [https://help.github.com/articles/fork-a-repo/ Fork the GEOS-Chem repositories]. Navigate to each appropriate [https://github.com/geoschem GEOS-Chem repository on GitHub] and click '''Fork''' in the top-right corner of the page.<br><br>
| + | |
| − | # Clone your forks of the GEOS-Chem repositories to your system:
| + | |
| − | #*<tt>git clone https://github.com/YOUR-USERNAME/geos-chem Code.12.0.0</tt>
| + | |
| − | #*<tt>git clone https://github.com/YOUR-USERNAME/geos-chem-unittest UT.12.0.0</tt>.<br><br>
| + | |
| − | # Add your modifications into a [https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell new branch] off of the master branch.<br><br>
| + | |
| − | # Test your update thoroughly and make sure that it works.
| + | |
| − | #*You can use the [[GEOS-Chem Unit Tester]] to make sure your code updates work for a given combination of met fields, resolutions, and simulation types.
| + | |
| − | #*A unit test looks for [[Parallelizing GEOS-Chem|parallelization errors]], [[Floating point math issues|floating point math issues]], [[Common GEOS-Chem error messages#Array-out-of-bounds error|array-out-of-bounds errors]], and [[Passing array arguments efficiently in GEOS-Chem|creation of array temporaries]].
| + | |
| − | #*For structural updates, we recommend running [[Performing_Difference_Tests_with_GEOS-Chem|difference tests]] often to ensure your updates don't impact model output.<br><br>
| + | |
| − | # Review the [[#Checklist for code update submissions|code update checklist]] and [[#Checklist for data submissions|data checklist]] below.<br><br>
| + | |
| − | # Create a [https://help.github.com/articles/creating-a-pull-request/ pull request in GitHub] (recommended) or a [https://www.devroom.io/2009/10/26/how-to-create-and-apply-a-patch-with-git/ Git patch file].
| + | |
| − | #* See our [https://github.com/geoschem/geos-chem/blob/dev/12.6.0/.github/PULL_REQUEST_TEMPLATE/create-a-geos-chem-pull-request.md pull request template on Github] for information to include.<br><br>
| + | |
| − | #The GEOS-Chem Support Team will add your changes to the standard code.
| + | |
| − | #*Your update may be bundled with other code updates and the [[GEOS-Chem_version_numbering_system#Numeric_versioning_system|GEOS-Chem version number ('''X.Y.Z''')]] will be changed.
| + | |
| − | #*The update will be validated following the [[GEOS-Chem_benchmarking|GEOS-Chem benchmarking procedure]].
| + | |
| − | | + | |
| − | === Checklist for code update submissions ===
| + | |
| − | | + | |
| − | #Use F90 free format whenever possible
| + | |
| − | #Include thorough comments throughout code updates
| + | |
| − | #Remove extraneous code updates (e.g. testing options, other science)
| + | |
| − | #Include full citations at the top of relevant source code modules
| + | |
| − | #Complete [[Developing_GCHP#GCHP_Updates_Required_with_GEOS-Chem_Classic_Updates|GCHP updates required with GEOS-Chem Classic updates]]
| + | |
| − | | + | |
| − | === Checklist for data submissions ===
| + | |
| − | | + | |
| − | #Choose a final file naming convention for all data files that are to be submitted.
| + | |
| − | #*Requesting files to be renamed after the benchmark process has begun can cause confusion and prevent reproducibility.<br><br>
| + | |
| − | #Make sure netCDF data files are [[The_COARDS_netCDF_conventions_for_earth_science_data|COARDS-compliant]]
| + | |
| − | #*Use [[Working_with_netCDF_data_files#Determining_if_a_netCDF_file_is_COARDS-compliant|<tt>isCoards</tt> script]] and include output in submission.<br><br>
| + | |
| − | #[[Working_with_netCDF_data_files#Concatenating_netCDF_files|Concatenate individual netCDF files together]] so as to reduce tne number of files that need to be opened.
| + | |
| − | #*e.g. If the data is a multi-year archive of monthly-mean data, create one file per year containing all data variables. Each data variable would have 12 timestamps, one for each month.
| + | |
| − | #*Reducing the number of files that have to be opened results in more efficient GEOS-Chem simulations.<br><br>
| + | |
| − | #Make sure files have been [[Working_with_netCDF_data_files#Chunking_and_deflating_a_netCDF_file_to_improve_I.2FO|chunked and deflated]].
| + | |
| − | #*Deflation level 1 is usually sufficient for most files.
| + | |
| − | #*e.g. <tt>./nc_chunk.pl myfile.nc 1</tt><br><br>
| + | |
| − | #Follow these additional steps to ensure data can also be read by GCHP:
| + | |
| − | #*All variables should be of type <tt>float</tt> (aka <tt>REAL*4</tt>) or <tt>double</tt> (aka <tt>REAL*8</tt>). The MAPL library used by GCHP cannot read integer data from netCDF files.
| + | |
| − | #*Use a recent reference date, if possible, for the <tt>time:units</tt> attribute. MAPL may have issues interpreting reference times such as 1750 which is prior to the Julian-to-Gregorian calendar switch.
| + | |
| − | #*Make sure the time units attribute is of format <tt>"x since YYYY-MM-DD HH:ss:MM"</tt> where x is a time unit such as hours or data, and YYYY, MM, DD, HH, ss, and MM are reference year, month, day, hour, second, and minute.
| + | |
| − | #*The first time value in each file should be 0, corresponding with the reference time.<br><br>
| + | |
| − | #Include updated HEMCO Configuration file (if the data will be read via HEMCO).
| + | |
| − | #*Submit this as a pull request in the [https://github.com/geoschem/geos-chem-unittest geos-chem-unittest repository on GitHub].<br><br>
| + | |
| − | #Include README file detailing data source, contents, etc.<br><br>
| + | |
| − | #Include script(s) used to process original data<br><br>
| + | |
| − | #Include a summary or description of the expected results (e.g. emission totals for each species)
| + | |
| − | | + | |
| − | == Further reading ==
| + | |
| − | | + | |
| − | *''[[Guide to using Git with GEOS-Chem]]''
| + | |
| − | *[[Git_and_Github_tutorials#Tutorials_about_Github|Github tutorials (including pull requests)]]
| + | |
