Difference between revisions of "Submitting updates for inclusion in GEOS-Chem"

From Geos-chem
Jump to: navigation, search
(Guidelines)
(Replaced content with "This content has been migrated to [https://geos-chem.readthedocs.io/en/latest/reference/CONTRIBUTING.html the '''Contributing guidelines''' page at <tt>geos-chem.readthedo...")
 
(16 intermediate revisions by 3 users 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.
+
# Create or log into your [https://github.com/ GitHub] account.
+
# [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.
+
# Clone your forks of the GEOS-Chem repositories to your system (e.g. <tt>git clone https://github.com/YOUR-USERNAME/geos-chem Code.12.0.0</tt>; git clone https://github.com/YOUR-USERNAME/geos-chem-unittest UT.12.0.).
+
# 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.
+
# 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.
+
# Review the [[#Checklist for code update submissions|code update checklist]] and [[#Checklist for data submissions|data checklist]] below.
+
# 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].
+
# Fill out and submit the [https://harvard.az1.qualtrics.com/jfe/form/SV_1ANYLLB4J9pjhCB '''GEOS-Chem Update Submission Form'''].
+
#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).
+
#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 ===
+
 
+
*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.
+
*[[Working_with_netCDF_data_files#Concatenating_netCDF_files|Concatenate netCDF files together]] whenever possible.
+
**e.g. Create one file per time period instead of one file per species per time period.
+
**Reducing the number of files that have to be opened results in more efficient GEOS-Chem simulations.
+
*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>
+
*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].
+
*Include README file detailing data source, contents, etc.
+
*Include script(s) used to process original data
+
*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)]]
+

Latest revision as of 16:03, 15 August 2022

This content has been migrated to the Contributing guidelines page at geos-chem.readthedocs.io.