|
|
| (15 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. 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).
| + | |
| − | # 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 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)]]
| + | |
