From 575e01633887b30f1600aa0beca9795fcae76fb1 Mon Sep 17 00:00:00 2001 From: lee1043 Date: Mon, 18 Sep 2023 19:25:09 -0700 Subject: [PATCH 01/19] Separate JSON: one JSON per run, instead of per model, to be better prepared for parallel processing --- .../mean_climate/mean_climate_driver.py | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/pcmdi_metrics/mean_climate/mean_climate_driver.py b/pcmdi_metrics/mean_climate/mean_climate_driver.py index 58d34cea3..7cf6ac950 100755 --- a/pcmdi_metrics/mean_climate/mean_climate_driver.py +++ b/pcmdi_metrics/mean_climate/mean_climate_driver.py @@ -291,18 +291,18 @@ print('compute metrics start') result_dict["RESULTS"][model][ref][run][region] = compute_metrics(varname, ds_test_dict[region], ds_ref_dict[region], debug=debug) - # write individual JSON - # --- single simulation, obs (need to accumulate later) / single variable - json_filename_tmp = "_".join([model, var, target_grid, regrid_tool, "metrics", ref]) - mean_climate_metrics_to_json( - os.path.join(metrics_output_path, var), - json_filename_tmp, - result_dict, - model=model, - run=run, - cmec_flag=cmec, - debug=debug - ) + # write individual JSON + # --- single simulation, obs (need to accumulate later) / single variable + json_filename_tmp = "_".join([var, model, run, target_grid, regrid_tool, "metrics", ref]) + mean_climate_metrics_to_json( + os.path.join(metrics_output_path, var), + json_filename_tmp, + result_dict, + model=model, + run=run, + cmec_flag=cmec, + debug=debug + ) except Exception as e: if debug: From 1ee929d8fb4dcb8338494a6f6710d327d177b0d1 Mon Sep 17 00:00:00 2001 From: lee1043 Date: Mon, 18 Sep 2023 19:45:20 -0700 Subject: [PATCH 02/19] bug fix --- .../mean_climate/lib/mean_climate_metrics_to_json.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/pcmdi_metrics/mean_climate/lib/mean_climate_metrics_to_json.py b/pcmdi_metrics/mean_climate/lib/mean_climate_metrics_to_json.py index b614f3559..0e42f7ec7 100644 --- a/pcmdi_metrics/mean_climate/lib/mean_climate_metrics_to_json.py +++ b/pcmdi_metrics/mean_climate/lib/mean_climate_metrics_to_json.py @@ -21,10 +21,11 @@ def mean_climate_metrics_to_json( for m in models_in_dict: if m == model: for ref in list(json_dict["RESULTS"][m].keys()): - runs_in_model_dict = list(json_dict["RESULTS"][m][ref].keys()) - for r in runs_in_model_dict: - if (r != run) and (run is not None): - del json_dict["RESULTS"][m][ref][r] + if ref != "units": + runs_in_model_dict = list(json_dict["RESULTS"][m][ref].keys()) + for r in runs_in_model_dict: + if (r != run) and (run is not None): + del json_dict["RESULTS"][m][ref][r] else: del json_dict["RESULTS"][m] # Write selected dict to JSON From 638e88d250acc1519a1b0da59b356711eb8bc6c4 Mon Sep 17 00:00:00 2001 From: lee1043 Date: Mon, 18 Sep 2023 23:00:56 -0700 Subject: [PATCH 03/19] improve for parallel run --- .../lib/create_mean_climate_parser.py | 9 +++++++ .../mean_climate/mean_climate_driver.py | 27 ++++++++++++------- 2 files changed, 27 insertions(+), 9 deletions(-) diff --git a/pcmdi_metrics/mean_climate/lib/create_mean_climate_parser.py b/pcmdi_metrics/mean_climate/lib/create_mean_climate_parser.py index 06633b1e0..ba542bdf1 100644 --- a/pcmdi_metrics/mean_climate/lib/create_mean_climate_parser.py +++ b/pcmdi_metrics/mean_climate/lib/create_mean_climate_parser.py @@ -266,4 +266,13 @@ def create_mean_climate_parser(): required=False, ) + parser.add_argument( + "--parallel", + type=bool, + dest="parallel", + default=False, + help="Option for running code in parallel mode: True / False (default)", + required=False, + ) + return parser diff --git a/pcmdi_metrics/mean_climate/mean_climate_driver.py b/pcmdi_metrics/mean_climate/mean_climate_driver.py index 7cf6ac950..a2860f70b 100755 --- a/pcmdi_metrics/mean_climate/mean_climate_driver.py +++ b/pcmdi_metrics/mean_climate/mean_climate_driver.py @@ -50,6 +50,7 @@ custom_obs = parameter.custom_observations debug = parameter.debug cmec = parameter.cmec +parallel = parameter.parallel if metrics_output_path is not None: metrics_output_path = parameter.metrics_output_path.replace('%(case_id)', case_id) @@ -146,6 +147,9 @@ # ------------- # variable loop # ------------- +if isinstance(vars, str): + vars = [vars] + for var in vars: if '_' in var or '-' in var: @@ -310,12 +314,17 @@ print('error occured for ', model, run) print(e) - # write collective JSON --- all models / all obs / single variable - json_filename = "_".join([var, target_grid, regrid_tool, "metrics"]) - mean_climate_metrics_to_json( - metrics_output_path, - json_filename, - result_dict, - cmec_flag=cmec, - ) - print('pmp mean clim driver completed') + # ======================================================================== + # Dictionary to JSON: collective JSON at the end of model_realization loop + # ------------------------------------------------------------------------ + if not parallel: + # write collective JSON --- all models / all obs / single variable + json_filename = "_".join([var, target_grid, regrid_tool, "metrics"]) + mean_climate_metrics_to_json( + metrics_output_path, + json_filename, + result_dict, + cmec_flag=cmec, + ) + +print('pmp mean clim driver completed') From 53419708d324ff77e42e307656a744748830cf5d Mon Sep 17 00:00:00 2001 From: lee1043 Date: Thu, 21 Sep 2023 17:17:58 -0700 Subject: [PATCH 04/19] update --- .../mean_climate/mean_climate_driver.py | 6 +-- pcmdi_metrics/mjo/lib/mjo_metric_calc.py | 44 ++++++++++++------- pcmdi_metrics/mjo/param/myParam_mjo.py | 2 +- pcmdi_metrics/mjo/scripts/parallel_driver.py | 4 +- pcmdi_metrics/mjo/scripts/run.sh | 7 +-- share/DefArgsCIA.json | 2 +- 6 files changed, 38 insertions(+), 27 deletions(-) diff --git a/pcmdi_metrics/mean_climate/mean_climate_driver.py b/pcmdi_metrics/mean_climate/mean_climate_driver.py index a2860f70b..1a9fd6c62 100755 --- a/pcmdi_metrics/mean_climate/mean_climate_driver.py +++ b/pcmdi_metrics/mean_climate/mean_climate_driver.py @@ -287,7 +287,7 @@ if debug: print('ds_test_tmp:', ds_test_tmp) - ds_test_dict[region].to_netcdf('_'.join([var, 'model', model, run, region + '.nc'])) + ds_test_dict[region].to_netcdf('_'.join([var, 'model', model, run, region, case_id + '.nc'])) if model == test_data_set[0] and run == realizations[0]: ds_ref_dict[region].to_netcdf('_'.join([var, 'ref', region + '.nc'])) @@ -297,7 +297,7 @@ # write individual JSON # --- single simulation, obs (need to accumulate later) / single variable - json_filename_tmp = "_".join([var, model, run, target_grid, regrid_tool, "metrics", ref]) + json_filename_tmp = "_".join([var, model, run, target_grid, regrid_tool, "metrics", ref, case_id]) mean_climate_metrics_to_json( os.path.join(metrics_output_path, var), json_filename_tmp, @@ -319,7 +319,7 @@ # ------------------------------------------------------------------------ if not parallel: # write collective JSON --- all models / all obs / single variable - json_filename = "_".join([var, target_grid, regrid_tool, "metrics"]) + json_filename = "_".join([var, target_grid, regrid_tool, "metrics", case_id]) mean_climate_metrics_to_json( metrics_output_path, json_filename, diff --git a/pcmdi_metrics/mjo/lib/mjo_metric_calc.py b/pcmdi_metrics/mjo/lib/mjo_metric_calc.py index ea6962071..49f9acc58 100644 --- a/pcmdi_metrics/mjo/lib/mjo_metric_calc.py +++ b/pcmdi_metrics/mjo/lib/mjo_metric_calc.py @@ -167,21 +167,35 @@ def mjo_metric_ewr_calculation( if plot: os.makedirs(outdir(output_type="graphics"), exist_ok=True) fout = os.path.join(outdir(output_type="graphics"), output_filename) - title = ( - mip.upper() - + ": " - + model - + " (" - + run - + ") \n" - + var.capitalize() - + ", " - + season - + " " - + str(startYear) - + "-" - + str(endYear) - ) + if model == 'obs': + title = ( + " OBS (" + + run + + ") \n" + + var.capitalize() + + ", " + + season + + " " + + str(startYear) + + "-" + + str(endYear) + ) + else: + title = ( + mip.upper() + + ": " + + model + + " (" + + run + + ") \n" + + var.capitalize() + + ", " + + season + + " " + + str(startYear) + + "-" + + str(endYear) + ) if cmmGrid: title += ", common grid (2.5x2.5deg)" plot_power(OEE, title, fout, ewr) diff --git a/pcmdi_metrics/mjo/param/myParam_mjo.py b/pcmdi_metrics/mjo/param/myParam_mjo.py index fddc93746..4456f66de 100644 --- a/pcmdi_metrics/mjo/param/myParam_mjo.py +++ b/pcmdi_metrics/mjo/param/myParam_mjo.py @@ -30,7 +30,7 @@ def find_latest(path): # Observation # ------------------------------------------------- reference_data_name = "GPCP-1-3" -reference_data_path = "/p/user_pub/PCMDIobs/PCMDIobs2/atmos/day/pr/GPCP-1-3/gn/v20200707/pr_day_GPCP-1-3_BE_gn_v20200707_19961002-20170101.nc" # noqa +reference_data_path = "/p/user_pub/PCMDIobs/obs4MIPs_legacy/PCMDIobs2/atmos/day/pr/GPCP-1-3/gn/v20200924/pr_day_GPCP-1-3_BE_gn_v20200924_19961002-20170101.nc" # noqa varOBS = "pr" ObsUnitsAdjust = (True, "multiply", 86400.0, "mm d-1") # kg m-2 s-1 to mm day-1 diff --git a/pcmdi_metrics/mjo/scripts/parallel_driver.py b/pcmdi_metrics/mjo/scripts/parallel_driver.py index d43cc9db5..17bcf20cb 100755 --- a/pcmdi_metrics/mjo/scripts/parallel_driver.py +++ b/pcmdi_metrics/mjo/scripts/parallel_driver.py @@ -97,10 +97,10 @@ # ================================================= # Generates list of command # ------------------------------------------------- -param_file = "../doc/myParam_mjo.py" +param_file = "../param/myParam_mjo.py" if debug: - param_file = "../doc/myParam_test.py" + param_file = "../param/myParam_test.py" print("number of models (debug mode):", len(models)) cmds_list = list() diff --git a/pcmdi_metrics/mjo/scripts/run.sh b/pcmdi_metrics/mjo/scripts/run.sh index fcca06219..8911b0897 100755 --- a/pcmdi_metrics/mjo/scripts/run.sh +++ b/pcmdi_metrics/mjo/scripts/run.sh @@ -1,9 +1,6 @@ #!/bin/sh set -a -# grim: pmp_nightly_20190628 -# gates: cdat82_20191107_py37, pmp_nightly_20190912 - #parallel=no parallel=yes @@ -17,7 +14,7 @@ mkdir -p log if [ $parallel == no ]; then echo 'parallel no' for mip in $mips; do - python -u mjo_metrics_driver.py -p ../doc/myParam_mjo.py --mip ${mip} >& log/log.${mip}.txt & + mjo_metrics_driver.py -p ../param/myParam_mjo.py --mip ${mip} >& log/log.${mip}.txt & disown done elif [ $parallel == yes ]; then @@ -25,7 +22,7 @@ elif [ $parallel == yes ]; then modnames="all" realization="all" for mip in $mips; do - python -u ./parallel_driver.py -p ../doc/myParam_mjo.py --mip ${mip} --num_workers $num_workers --modnames $modnames --realization $realization >& log/log.parallel.${mip}.txt & + python -u ./parallel_driver.py -p ../param/myParam_mjo.py --mip ${mip} --num_workers $num_workers --modnames $modnames --realization $realization >& log/log.parallel.${mip}.txt & disown done fi diff --git a/share/DefArgsCIA.json b/share/DefArgsCIA.json index 8507f33ba..cd33a055d 100644 --- a/share/DefArgsCIA.json +++ b/share/DefArgsCIA.json @@ -163,4 +163,4 @@ ], "help":"A list of variables to be processed" } -} +} \ No newline at end of file From b3914789c9070e0abe6f38e21a5c78a21104a34d Mon Sep 17 00:00:00 2001 From: lee1043 Date: Thu, 21 Sep 2023 17:19:44 -0700 Subject: [PATCH 05/19] clean up --- pcmdi_metrics/mjo/scripts/parallel_driver.py | 1 - 1 file changed, 1 deletion(-) diff --git a/pcmdi_metrics/mjo/scripts/parallel_driver.py b/pcmdi_metrics/mjo/scripts/parallel_driver.py index 17bcf20cb..f8179a838 100755 --- a/pcmdi_metrics/mjo/scripts/parallel_driver.py +++ b/pcmdi_metrics/mjo/scripts/parallel_driver.py @@ -148,7 +148,6 @@ for r, run in enumerate(runs_list): # command line for queue cmd = [ - "python", "mjo_metrics_driver.py", "-p", param_file, From 93dbc974f74cd70be91d02d81f4a4c4f183a3706 Mon Sep 17 00:00:00 2001 From: lee1043 Date: Sun, 24 Sep 2023 19:39:06 -0700 Subject: [PATCH 06/19] pre-commit fix --- share/DefArgsCIA.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/share/DefArgsCIA.json b/share/DefArgsCIA.json index cd33a055d..8507f33ba 100644 --- a/share/DefArgsCIA.json +++ b/share/DefArgsCIA.json @@ -163,4 +163,4 @@ ], "help":"A list of variables to be processed" } -} \ No newline at end of file +} From 740e2ef640ccb545342c82857f14cb251e8414f8 Mon Sep 17 00:00:00 2001 From: Ana Ordonez Date: Mon, 25 Sep 2023 13:38:27 -0700 Subject: [PATCH 07/19] Update variability_across_timescales_PS_driver.py --- .../variability_across_timescales_PS_driver.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/pcmdi_metrics/precip_variability/variability_across_timescales_PS_driver.py b/pcmdi_metrics/precip_variability/variability_across_timescales_PS_driver.py index c606be499..c5fd773b0 100644 --- a/pcmdi_metrics/precip_variability/variability_across_timescales_PS_driver.py +++ b/pcmdi_metrics/precip_variability/variability_across_timescales_PS_driver.py @@ -3,8 +3,6 @@ import glob import os -from genutil import StringConstructor - from pcmdi_metrics.mean_climate.lib.pmp_parser import PMPParser from pcmdi_metrics.precip_variability.lib import ( AddParserArgument, @@ -38,9 +36,11 @@ outdir = StringConstructor( str(outdir_template(output_type="%(output_type)", mip=mip, case_id=case_id)) ) +outdir_template = outdir_template.replace("%(mip)",mip).replace("%(case_id)",case_id) for output_type in ["graphics", "diagnostic_results", "metrics_results"]: - os.makedirs(outdir(output_type=output_type), exist_ok=True) - print(outdir(output_type=output_type)) + outdir = outdir_template.replace("%(output_type)",output_type) + os.makedirs(outdir, exist_ok=True) + print(outdir) # Check data in advance file_list = sorted(glob.glob(os.path.join(modpath, mod))) @@ -57,5 +57,5 @@ syr = prd[0] eyr = prd[1] precip_variability_across_timescale( - file_list, syr, eyr, dfrq, mip, dat, var, fac, nperseg, noverlap, outdir, cmec + file_list, syr, eyr, dfrq, mip, dat, var, fac, nperseg, noverlap, outdir_template, cmec ) From fa5040d47bfd392f39022aa4e64f920b2784a19e Mon Sep 17 00:00:00 2001 From: Ana Ordonez Date: Mon, 25 Sep 2023 13:40:01 -0700 Subject: [PATCH 08/19] Remove genutil constructor --- .../lib/lib_variability_across_timescales.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pcmdi_metrics/precip_variability/lib/lib_variability_across_timescales.py b/pcmdi_metrics/precip_variability/lib/lib_variability_across_timescales.py index 5f54506c7..74352ec9a 100644 --- a/pcmdi_metrics/precip_variability/lib/lib_variability_across_timescales.py +++ b/pcmdi_metrics/precip_variability/lib/lib_variability_across_timescales.py @@ -63,7 +63,7 @@ def precip_variability_across_timescale( # Write data (nc file) outfilename = "PS_pr." + str(dfrq) + "_regrid.180x90_" + dat + ".nc" custom_dataset = xr.merge([freqs, ps, rn, sig95]) - custom_dataset.to_netcdf(path=os.path.join(outdir(output_type="diagnostic_results"), outfilename)) + custom_dataset.to_netcdf(path=os.path.join(outdir.replace("%(output_type)","diagnostic_results"), outfilename)) # Power spectum of anomaly freqs, ps, rn, sig95 = Powerspectrum(anom, nperseg, noverlap) @@ -72,7 +72,7 @@ def precip_variability_across_timescale( # Write data (nc file) outfilename = "PS_pr." + str(dfrq) + "_regrid.180x90_" + dat + "_unforced.nc" custom_dataset = xr.merge([freqs, ps, rn, sig95]) - custom_dataset.to_netcdf(path=os.path.join(outdir(output_type="diagnostic_results"), outfilename)) + custom_dataset.to_netcdf(path=os.path.join(outdir.replace("%(output_type)","diagnostic_results"), outfilename)) # Write data (json file) psdmfm["RESULTS"][dat] = {} @@ -83,7 +83,7 @@ def precip_variability_across_timescale( "PS_pr." + str(dfrq) + "_regrid.180x90_area.freq.mean_" + dat + ".json" ) JSON = pcmdi_metrics.io.base.Base( - outdir(output_type="metrics_results"), outfilename + outdir.replace("%(output_type)","metrics_results"), outfilename ) JSON.write( psdmfm, From 5f44c39e603a53a5cffbf7ef5a9245ce25d915f1 Mon Sep 17 00:00:00 2001 From: Ana Ordonez Date: Mon, 25 Sep 2023 13:53:02 -0700 Subject: [PATCH 09/19] Remove string constructor --- .../variability_across_timescales_PS_driver.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/pcmdi_metrics/precip_variability/variability_across_timescales_PS_driver.py b/pcmdi_metrics/precip_variability/variability_across_timescales_PS_driver.py index c5fd773b0..5b1ee951d 100644 --- a/pcmdi_metrics/precip_variability/variability_across_timescales_PS_driver.py +++ b/pcmdi_metrics/precip_variability/variability_across_timescales_PS_driver.py @@ -33,9 +33,6 @@ # Create output directory case_id = param.case_id outdir_template = param.process_templated_argument("results_dir") -outdir = StringConstructor( - str(outdir_template(output_type="%(output_type)", mip=mip, case_id=case_id)) -) outdir_template = outdir_template.replace("%(mip)",mip).replace("%(case_id)",case_id) for output_type in ["graphics", "diagnostic_results", "metrics_results"]: outdir = outdir_template.replace("%(output_type)",output_type) From 34c54c6546cd108c07ea008e86db187ce591c8f2 Mon Sep 17 00:00:00 2001 From: Ana Ordonez Date: Mon, 25 Sep 2023 13:59:26 -0700 Subject: [PATCH 10/19] Remove process templated arg --- .../variability_across_timescales_PS_driver.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pcmdi_metrics/precip_variability/variability_across_timescales_PS_driver.py b/pcmdi_metrics/precip_variability/variability_across_timescales_PS_driver.py index 5b1ee951d..aeebb6856 100644 --- a/pcmdi_metrics/precip_variability/variability_across_timescales_PS_driver.py +++ b/pcmdi_metrics/precip_variability/variability_across_timescales_PS_driver.py @@ -32,7 +32,7 @@ # Create output directory case_id = param.case_id -outdir_template = param.process_templated_argument("results_dir") +outdir_template = param.results_dir outdir_template = outdir_template.replace("%(mip)",mip).replace("%(case_id)",case_id) for output_type in ["graphics", "diagnostic_results", "metrics_results"]: outdir = outdir_template.replace("%(output_type)",output_type) From 68a9a2577ba71958727954cb5e998b42e1d07e44 Mon Sep 17 00:00:00 2001 From: Ana Ordonez Date: Mon, 25 Sep 2023 14:05:57 -0700 Subject: [PATCH 11/19] Force str type --- .../variability_across_timescales_PS_driver.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pcmdi_metrics/precip_variability/variability_across_timescales_PS_driver.py b/pcmdi_metrics/precip_variability/variability_across_timescales_PS_driver.py index aeebb6856..45d4e4ee1 100644 --- a/pcmdi_metrics/precip_variability/variability_across_timescales_PS_driver.py +++ b/pcmdi_metrics/precip_variability/variability_across_timescales_PS_driver.py @@ -33,7 +33,7 @@ # Create output directory case_id = param.case_id outdir_template = param.results_dir -outdir_template = outdir_template.replace("%(mip)",mip).replace("%(case_id)",case_id) +outdir_template = outdir_template.replace("%(mip)",str(mip)).replace("%(case_id)",str(case_id)) for output_type in ["graphics", "diagnostic_results", "metrics_results"]: outdir = outdir_template.replace("%(output_type)",output_type) os.makedirs(outdir, exist_ok=True) From 69f60f9d9157ddb7b75e336d1a0ee92bba688a86 Mon Sep 17 00:00:00 2001 From: Jiwoo Lee Date: Tue, 3 Oct 2023 16:31:23 -0700 Subject: [PATCH 12/19] Update issue templates --- .github/ISSUE_TEMPLATE/bug_report.md | 38 +++++++++++++++++++ .../ISSUE_TEMPLATE/documentation-update.md | 10 +++++ .github/ISSUE_TEMPLATE/feature_request.md | 20 ++++++++++ .github/ISSUE_TEMPLATE/questions.md | 10 +++++ 4 files changed, 78 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/documentation-update.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/ISSUE_TEMPLATE/questions.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 000000000..a79b5cb8b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,38 @@ +--- +name: Bug report +about: " File a bug report to help us improve PMP " +title: '' +labels: '' +assignees: '' + +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**To Reproduce** +Steps to reproduce the behavior: +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Screenshots** +If applicable, add screenshots to help explain your problem. + +**Desktop (please complete the following information):** + - OS: [e.g. iOS] + - Browser [e.g. chrome, safari] + - Version [e.g. 22] + +**Smartphone (please complete the following information):** + - Device: [e.g. iPhone6] + - OS: [e.g. iOS8.1] + - Browser [e.g. stock browser, safari] + - Version [e.g. 22] + +**Additional context** +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/documentation-update.md b/.github/ISSUE_TEMPLATE/documentation-update.md new file mode 100644 index 000000000..d9c891651 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation-update.md @@ -0,0 +1,10 @@ +--- +name: Documentation Update +about: 'Update PMP documentation ' +title: '' +labels: '' +assignees: '' + +--- + + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 000000000..0fb08a38f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Suggest an idea for PMP +title: '' +labels: '' +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/questions.md b/.github/ISSUE_TEMPLATE/questions.md new file mode 100644 index 000000000..e66828798 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/questions.md @@ -0,0 +1,10 @@ +--- +name: Questions +about: Ask questions and discuss with other PMP community members here. +title: '' +labels: '' +assignees: '' + +--- + +Ask questions and discuss with other PMP community members here. Please browse the PMP Discussions Forum or PMP documentation first before asking a question to make sure it is not already answered. If you can't find an answer, please include a self-contained reproducible example with your question if possible. Thanks! From 5de3b82c8e980e369257fd17d54cff76fe88bb7d Mon Sep 17 00:00:00 2001 From: Jiwoo Lee Date: Tue, 3 Oct 2023 16:45:54 -0700 Subject: [PATCH 13/19] add templates --- .github/DISCUSSION_TEMPLATE/2-questions.yml | 70 +++++++++++++++++++ .github/ISSUE_TEMPLATE/bug_report.md | 38 ---------- .github/ISSUE_TEMPLATE/bug_report.yml | 61 ++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 11 +++ .../ISSUE_TEMPLATE/documentation-update.md | 10 --- .github/ISSUE_TEMPLATE/documentation.yml | 15 ++++ .github/ISSUE_TEMPLATE/feature_request.md | 20 ------ .github/ISSUE_TEMPLATE/feature_request.yml | 42 +++++++++++ .github/ISSUE_TEMPLATE/questions.md | 10 --- 9 files changed, 199 insertions(+), 78 deletions(-) create mode 100644 .github/DISCUSSION_TEMPLATE/2-questions.yml delete mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml delete mode 100644 .github/ISSUE_TEMPLATE/documentation-update.md create mode 100644 .github/ISSUE_TEMPLATE/documentation.yml delete mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml delete mode 100644 .github/ISSUE_TEMPLATE/questions.md diff --git a/.github/DISCUSSION_TEMPLATE/2-questions.yml b/.github/DISCUSSION_TEMPLATE/2-questions.yml new file mode 100644 index 000000000..1bb506f44 --- /dev/null +++ b/.github/DISCUSSION_TEMPLATE/2-questions.yml @@ -0,0 +1,70 @@ +labels: [question] +body: + - type: markdown + attributes: + value: | + Thanks for your interest in PMP! Please follow the template below to ensure the development team and community can help you effectively. + + - type: checkboxes + id: checks + attributes: + label: Question criteria + description: Please confirm and check all the following options. + options: + - label: I added a descriptive title here. + required: true + - label: I searched the [PMP GitHub Discussions](https://github.com/PCMDI/pcmdi_metrics/discussions) to find a similar question and didn't find it. + required: true + - label: I searched the [PMP documentation](http://pcmdi.github.io/pcmdi_metrics/). + required: true + + - type: textarea + id: your-question + attributes: + label: Describe your question + description: | + Please help the community help you. The more specific you can be, the easier it will be to help. + validations: + required: true + + - type: textarea + id: possible-answers + attributes: + label: Are there are any possible answers you came across? + description: | + This will help others determine if you're on the right track. Include links to pages you've researched (e.g., software docs, Stack Overflow posts). + + - type: textarea + id: sample-code + attributes: + label: Minimal Complete Verifiable Example (MVCE) + description: | + Minimal, self-contained copy-pastable example that generates the question/issue if possible. Please be concise with code posted (e.g., module imports, publicly accessible files). + Examples that follow these guidelines are easier to parse. This section will be automatically formatted into code, so no need for markdown backticks. + + See guidelines below on how to provide a good MCVE: + + - [Minimal Complete Verifiable Examples](https://stackoverflow.com/help/mcve) + - [Craft Minimal Bug Reports](http://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports) + render: python + + - type: textarea + id: log-output + attributes: + label: Relevant log output + description: Please copy and paste any relevant output. This will be automatically formatted into code, so no need for markdown backticks. + render: python + + - type: textarea + id: show-versions + attributes: + label: Environment + description: | + If an MVCE and log output was provided, share your PMP version and some other information if your environment here + + - type: textarea + id: extra + attributes: + label: Anything else we need to know? + description: | + Please describe any other information you want to share. diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index a79b5cb8b..000000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -name: Bug report -about: " File a bug report to help us improve PMP " -title: '' -labels: '' -assignees: '' - ---- - -**Describe the bug** -A clear and concise description of what the bug is. - -**To Reproduce** -Steps to reproduce the behavior: -1. Go to '...' -2. Click on '....' -3. Scroll down to '....' -4. See error - -**Expected behavior** -A clear and concise description of what you expected to happen. - -**Screenshots** -If applicable, add screenshots to help explain your problem. - -**Desktop (please complete the following information):** - - OS: [e.g. iOS] - - Browser [e.g. chrome, safari] - - Version [e.g. 22] - -**Smartphone (please complete the following information):** - - Device: [e.g. iPhone6] - - OS: [e.g. iOS8.1] - - Browser [e.g. stock browser, safari] - - Version [e.g. 22] - -**Additional context** -Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 000000000..f72e03459 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,61 @@ +name: Bug Report +description: File a bug report to help us improve PMP +title: "[Bug]: " +labels: ["Type: Bug"] +assignees: [] +body: + - type: textarea + id: what-happened + attributes: + label: What happened? + description: | + Thanks for reporting a bug! Please describe what you were trying to get done. + Tell us what happened, what went wrong. + validations: + required: true + + - type: textarea + id: what-did-you-expect-to-happen + attributes: + label: What did you expect to happen? Are there are possible answers you came across? + description: | + Describe what you expected to happen. Include links to pages you've researched (e.g., software docs, Stack Overflow posts). + validations: + required: false + + - type: textarea + id: sample-code + attributes: + label: Minimal Complete Verifiable Example (MVCE) + description: | + Minimal, self-contained copy-pastable example that generates the issue if possible. Please be concise with code posted (e.g., module imports, publicly accessible files). + Bug reports that follow these guidelines are easier to diagnose, and so are often handled much more quickly. This section will be automatically formatted into code, so no need for markdown backticks. + + See guidelines below on how to provide a good MCVE: + + - [Minimal Complete Verifiable Examples](https://stackoverflow.com/help/mcve) + - [Craft Minimal Bug Reports](http://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports) + render: python + + - type: textarea + id: log-output + attributes: + label: Relevant log output + description: Please copy and paste any relevant output. This will be automatically formatted into code, so no need for markdown backticks. + render: python + + - type: textarea + id: extra + attributes: + label: Anything else we need to know? + description: | + Please describe any other information you want to share. + + - type: textarea + id: show-versions + attributes: + label: Environment + description: | + Please share some information about your environment. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..c2816362f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: true +contact_links: + - name: Questions (PMP) + url: https://github.com/PCMDI/pcmdi_metrics/discussions + about: | + Ask questions and discuss with other PMP community members here. Please + browse the PMP Discussions Forum or PMP documentation first before asking a + question to make sure it is not already answered. If you can't find an + answer, please include a self-contained reproducible example with your + question if possible. Thanks! + diff --git a/.github/ISSUE_TEMPLATE/documentation-update.md b/.github/ISSUE_TEMPLATE/documentation-update.md deleted file mode 100644 index d9c891651..000000000 --- a/.github/ISSUE_TEMPLATE/documentation-update.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -name: Documentation Update -about: 'Update PMP documentation ' -title: '' -labels: '' -assignees: '' - ---- - - diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml new file mode 100644 index 000000000..fd5b1e767 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.yml @@ -0,0 +1,15 @@ +name: Documentation Update +description: Update PMP documentation +title: "[Doc]: " +labels: ["Type: Documentation"] +assignees: [] +body: + - type: textarea + id: description + attributes: + label: Describe your documentation update + description: | + Concise description of why the documentation is being updated (e.g., missing content for new feature, typo) + If this is related to an issue or PR, please mention it. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index 0fb08a38f..000000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for PMP -title: '' -labels: '' -assignees: '' - ---- - -**Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -**Describe the solution you'd like** -A clear and concise description of what you want to happen. - -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. - -**Additional context** -Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 000000000..70ef8982c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,42 @@ +name: Feature Request +description: Suggest an idea for PMP +title: "[Feature]: " +labels: ["Type: Enhancement"] +assignees: [] +body: + - type: textarea + id: description + attributes: + label: Is your feature request related to a problem? + description: | + Please do a quick search of existing issues to make sure that this has not been asked before. + Please provide a clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Describe the solution you'd like + description: | + A clear and concise description of what you want to happen. + validations: + required: false + + - type: textarea + id: alternatives + attributes: + label: Describe alternatives you've considered + description: | + A clear and concise description of any alternative solutions or features you've considered. + validations: + required: false + + - type: textarea + id: additional-context + attributes: + label: Additional context + description: | + Add any other context about the feature request here. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/questions.md b/.github/ISSUE_TEMPLATE/questions.md deleted file mode 100644 index e66828798..000000000 --- a/.github/ISSUE_TEMPLATE/questions.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -name: Questions -about: Ask questions and discuss with other PMP community members here. -title: '' -labels: '' -assignees: '' - ---- - -Ask questions and discuss with other PMP community members here. Please browse the PMP Discussions Forum or PMP documentation first before asking a question to make sure it is not already answered. If you can't find an answer, please include a self-contained reproducible example with your question if possible. Thanks! From 99fdea443c1195c9ef729041ea099d272723f2f1 Mon Sep 17 00:00:00 2001 From: Jiwoo Lee Date: Tue, 3 Oct 2023 16:58:09 -0700 Subject: [PATCH 14/19] add vscode setup file --- .vscode/pcmdi_metrics.code-workspace | 53 ++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 .vscode/pcmdi_metrics.code-workspace diff --git a/.vscode/pcmdi_metrics.code-workspace b/.vscode/pcmdi_metrics.code-workspace new file mode 100644 index 000000000..93362f2d5 --- /dev/null +++ b/.vscode/pcmdi_metrics.code-workspace @@ -0,0 +1,53 @@ +// This file stores the pcmdi_metrics repository's VS Code workspace settings. +// Simply open up this file in VS Code and the editor will be automatically configured using this file. +// Workspace settings take precedence over your user settings. +{ + "folders": [ + { + "path": ".." + } + ], + "settings": { + // =================== + // Editor settings + // =================== + "editor.formatOnSave": true, + // =================== + // Python settings + // =================== + "[python]": { + // editor.rulers: [comments, max line length, wrap line length], + // Black does not wrap comments. + "editor.rulers": [80, 88, 120], + "editor.wordWrap": "wordWrapColumn", + "editor.wordWrapColumn": 120, + "editor.defaultFormatter": "ms-python.black-formatter" + }, + "black-formatter.importStrategy": "fromEnvironment", + // Code Formatting and Linting + // --------------------------- + "flake8.args": ["--config=setup.cfg"], + "flake8.importStrategy": "fromEnvironment", + // Type checking + // --------------------------- + "mypy-type-checker.args": ["--config=pyproject.toml"], + "mypy-type-checker.importStrategy": "fromEnvironment", + // Testing + // --------------------------- + "python.testing.unittestEnabled": false, + "python.testing.pytestEnabled": true, + // NOTE: Debugger doesn't work if pytest-cov is enabled, so set "--no-cov" + // https://github.com/microsoft/vscode-python/issues/693 + "python.testing.pytestArgs": ["--no-cov"], + // =================== + // Extension settings + // =================== + "jupyter.notebookFileRoot": "${workspaceFolder}", + "autoDocstring.docstringFormat": "numpy", + "[restructuredtext]": { + "editor.rulers": [88, 120], + "editor.wordWrap": "wordWrapColumn", + "editor.wordWrapColumn": 120 + } + } +} From 08941dba732085e10f8ca63688b994dfe84714ee Mon Sep 17 00:00:00 2001 From: Jiwoo Lee Date: Tue, 3 Oct 2023 17:03:25 -0700 Subject: [PATCH 15/19] clean up --- docs/contributing.rst | 356 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 356 insertions(+) create mode 100644 docs/contributing.rst diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 000000000..e39aaa26a --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,356 @@ +.. highlight:: shell + +============ +Contributing +============ + +Contributions are welcome and greatly appreciated! Every little bit helps, and credit will always be given. + +Types of Contributions +---------------------- + +PCMDI Metrics Package (PMP) includes issue templates based on the contribution type: https://github.com/PCMDI/pcmdi_metrics/issues/new/choose. +Note, new contributions must be made under the Apache-2.0 with LLVM exception license. + +Bug Report +~~~~~~~~~~ + +Look through the `GitHub Issues`_ for bugs to fix. Any unassigned issues tagged with "Type: Bug" is open for implementation. + +Feature Request +~~~~~~~~~~~~~~~ + +Look through the `GitHub Issues`_ for feature suggestions. Any unassigned issues tagged with "Type: Enhancement" is open for implementation. + +If you are proposing a feature: + +* Explain in detail how it would work. +* Keep the scope as narrow as possible, to make it easier to implement. +* Remember that this is a open-source project, and that contributions are welcome :) + +Features must meet the following criteria before they are considered for implementation: + +1. Feature is not implemented by ``xarray`` +2. Feature is not implemented in another actively developed xarray-based package + + * For example, `cf_xarray`_ already handles interpretation of `CF convention`_ attributes on xarray objects + +3. Feature is not limited to specific use cases (e.g., data quality issues) +4. Feature is generally reusable +5. Feature is relatively simple and lightweight to implement and use + +Documentation Update +~~~~~~~~~~~~~~~~~~~~ + +Help improve PMP's documentation, whether that be the Sphinx documentation or the API docstrings. + +Community Discussion +~~~~~~~~~~~~~~~~~~~~ + +Take a look at the `GitHub Discussions`_ page to get involved, share ideas, or ask questions. + +.. _cf_xarray: https://cf-xarray.readthedocs.io/en/latest/index.html +.. _CF convention: http://cfconventions.org/ +.. _GitHub Issues: https://github.com/PCMDI/pcmdi_metrics/issues +.. _GitHub Discussions: https://github.com/PCMDI/pcmdi_metrics/discussions + +Version Control +--------------- + +The repository uses branch-based (core team) and fork-based (external collaborators) +Git workflows with tagged software releases. + +.. figure:: _static/git-flow.svg + :alt: Git Flow Diagram + +Guidelines +~~~~~~~~~~ + +1. ``main`` must always be deployable +2. All changes are made through support branches +3. Rebase with the latest ``main`` to avoid/resolve conflicts +4. Make sure pre-commit quality assurance checks pass when committing (enforced in CI/CD build) +5. Open a pull request early for discussion +6. Once the CI/CD build passes and pull request is approved, squash and rebase your commits +7. Merge pull request into ``main`` and delete the branch + +Things to Avoid +~~~~~~~~~~~~~~~ + +1. Don't merge in broken or commented out code +2. Don't commit directly to ``main`` + + * There are branch-protection rules for ``main`` + +3. Don't merge with conflicts. Instead, handle conflicts upon rebasing + +Source: https://gist.github.com/jbenet/ee6c9ac48068889b0912 + +Pre-commit +~~~~~~~~~~ +The repository uses the pre-commit package to manage pre-commit hooks. +These hooks help with quality assurance standards by identifying simple issues +at the commit level before submitting code reviews. + +.. figure:: _static/pre-commit-flow.svg + :alt: Pre-commit Flow Diagram + + pre-commit Flow + + +Get Started +------------ + +Ready to contribute? Here's how to set up PMP for local development. + +VS Code, the editor of choice +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We recommend using VS Code as your IDE because it is open-source and has great Python development support. + +Get VS Code here: https://code.visualstudio.com + +VS Code Setup +^^^^^^^^^^^^^ +PMP includes a VS Code workspace file (``.vscode/pcmdi_metrics.code-setting``). This file automatically configures your IDE with the quality assurance tools, code line-length rulers, and more. + +Make sure to follow the :ref:`Local Development` section below. + +Recommended VS Code Extensions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + * `Python `_ + * `Pylance `_ + * `Python Docstring Generator `_ + * `Python Type Hint `_ + * `Better Comments `_ + * `Jupyter `_ + * `Visual Studio Intellicode `_ + + +.. _Local Development: + +Local Development +~~~~~~~~~~~~~~~~~ + +1. Download and install Conda + + Linux + :: + + $ wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh + $ bash ./Miniconda3-latest-Linux-x86_64.sh + Do you wish the installer to initialize Miniconda3 by running conda init? [yes|no] yes + + + MacOS + :: + + $ wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh + $ bash ./Miniconda3-latest-MacOSX-x86_64.sh + Do you wish the installer to initialize Miniconda3 by running conda init? [yes|no] yes + +2. Fork the ``pcmdi_metrics`` repo on GitHub. + + - If you are a maintainer, you can clone and branch directly from the root repository here: https://github.com/PCMDI/pcmdi_metrics + +3. Clone your fork locally:: + + $ git clone git@github.com:your_name_here/pcmdi_metrics.git + +4. Open ``.vscode/pcmdi_metrics.code-settings`` in VS Code + + +5. Create and activate Conda development environment:: + + $ cd pcmdi_metrics + $ conda env create -f conda-env/dev.yml + $ conda activate pcmdi_metrics_dev + +6. Set VS Code Python interpretor to ``pcmdi_metrics_dev`` + +7. Install pre-commit:: + + $ pre-commit install + pre-commit installed at .git/hooks/pre-commit + +8. Create a branch for local development and make changes:: + + $ git checkout -b + +9. `` During or after making changes, check for formatting or linting issues using pre-commit:: + + # Step 9 performs this automatically on staged files in a commit + $ pre-commit run --all-files + + Trim Trailing Whitespace.................................................Passed + Fix End of Files.........................................................Passed + Check Yaml...............................................................Passed + black....................................................................Passed + isort....................................................................Passed + flake8...................................................................Passed + mypy.....................................................................Passed + +11. Commit your changes:: + + $ git add . + $ git commit -m + + Trim Trailing Whitespace.................................................Passed + Fix End of Files.........................................................Passed + Check Yaml...............................................................Passed + black....................................................................Passed + isort....................................................................Passed + flake8...................................................................Passed + +12. Make sure pre-commit QA checks pass. Otherwise, fix any caught issues. + + - Most of the tools fix issues automatically so you just need to re-stage the files. + - flake8 and mypy issues must be fixed automatically. + +13. Push changes:: + + $ git push origin + +14. Submit a pull request through the GitHub website. + + +Pull Request Guidelines +----------------------- + +Before you submit a pull request, check that it meets these guidelines: + +1. The pull request should include tests for new or modified code. +2. Link issues to pull requests. +3. If the pull request adds functionality, the docs should be updated. Put + your new functionality into a function with a docstring, and add the + feature to the list in README.rst. +4. Squash and rebase commits for a clean and navigable Git history. + +When you open a pull request on GitHub, there is a template available for use. + + +Style Guide +----------- + +PMP integrates the Black code formatter for code styling. If you want to learn more, please read about it `here `__. + +PMP also leverages `Python Type Annotations `_ to help the project scale. +`mypy `_ performs optional static type checking through pre-commit. + +Testing +------- + +Testing your local changes are important to ensure long-term maintainability and extensibility of the project. +Since PMP is an open source library, we aim to avoid as many bugs as possible from reaching the end-user. + +To get started, here are guides on how to write tests using pytest: + +- https://docs.pytest.org/en/latest/ +- https://docs.python-guide.org/writing/tests/#py-test + +In most cases, if a function is hard to test, it is usually a symptom of being too complex (high cyclomatic-complexity). + +DOs for Testing +~~~~~~~~~~~~~~~ + +* *DO* write tests for new or refactored code +* *DO* try to follow test-driven-development +* *DO* use the Coverage reports to see lines of code that need to be tested +* *DO* focus on simplistic, small, reusable modules for unit testing +* *DO* cover as many edge cases as possible when testing + +DON'Ts for Testing +~~~~~~~~~~~~~~~~~~ + +* *DON'T* push or merge untested code +* *DON'T* introduce tests that fail or produce warnings + +Documenting Code +---------------- + +If you are using VS code, the `Python Docstring Generator `_ extension can be used to auto-generate a docstring snippet once a function/class has been written. +If you want the extension to generate docstrings in Sphinx format, you must set the ``"autoDocstring.docstringFormat": "sphinx"`` setting, under File > Preferences > Settings. + +Note that it is best to write the docstrings once you have fully defined the function/class, as then the extension will generate the full docstring. +If you make any changes to the code once a docstring is generated, you will have to manually go and update the affected docstrings. + +More info on docstrings here: https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html + +DOs for Documenting Code +~~~~~~~~~~~~~~~~~~~~~~~~ + +* *DO* explain **why** something is done, its purpose, and its goal. The code shows **how** it is done, so commenting on this can be redundant. +* *DO* explain ambiguity or complexities to avoid confusion +* *DO* embrace documentation as an integral part of the overall development process +* *DO* treat documenting as code and follow principles such as *Don't Repeat Yourself* and *Easier to Change* + +DON'Ts for Documenting Code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* *DON'T* write comments as a crutch for poor code +* *DON'T* comment *every* function, data structure, type declaration + +Developer Tips +-------------- + +* flake8 will warn you if the cyclomatic complexity of a function is too high. + + * https://github.com/PyCQA/mccabe + + +FAQs +---- + +.. _Why squash and rebase?: + +Why squash and rebase commits? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before you merge a support branch back into ``main``, the branch is typically squashed down to a single buildable commit, and then rebased on top of the main repo's ``main`` branch. + +Why? + +* Ensures build passes from the commit +* Cleans up Git history for easy navigation +* Makes collaboration and review process more efficient +* Makes handling conflicts from rebasing simple since you only have to deal with conflicted commits + + +How do I squash and rebase commits? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* Use GitHub's Squash and Merge feature in the pull request + + * You still need to rebase on the latest ``main`` if ``main`` is ahead of your branch. + +* Manually squash and rebase + + 1. `` Sync your fork of ``main`` (aka ``origin``) with the root ``main`` (aka ``upstream``) :: + + git checkout main + git rebase upstream/main + git push -f origin main + + 2. Get the SHA of the commit OR number of commits to rebase to :: + + git checkout + git log --graph --decorate --pretty=oneline --abbrev-commit + + 3. Squash commits:: + + git rebase -i [SHA] + + # OR + + git rebase -i HEAD~[NUMBER OF COMMITS] + + 4. Rebase branch onto ``main`` :: + + git rebase main + git push -f origin + + 5. Make sure your squashed commit messages are refined + + 6. Force push to remote branch :: + + git push -f origin From 1db112f1931d6e2bce5f916e56f3dda1eb059bcb Mon Sep 17 00:00:00 2001 From: Jiwoo Lee Date: Tue, 3 Oct 2023 17:07:07 -0700 Subject: [PATCH 16/19] clean up --- docs/contributing.rst | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index e39aaa26a..44c4c7fd7 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -28,17 +28,6 @@ If you are proposing a feature: * Keep the scope as narrow as possible, to make it easier to implement. * Remember that this is a open-source project, and that contributions are welcome :) -Features must meet the following criteria before they are considered for implementation: - -1. Feature is not implemented by ``xarray`` -2. Feature is not implemented in another actively developed xarray-based package - - * For example, `cf_xarray`_ already handles interpretation of `CF convention`_ attributes on xarray objects - -3. Feature is not limited to specific use cases (e.g., data quality issues) -4. Feature is generally reusable -5. Feature is relatively simple and lightweight to implement and use - Documentation Update ~~~~~~~~~~~~~~~~~~~~ From c5204da966b20589f273c9e29a57cdfc861cf50b Mon Sep 17 00:00:00 2001 From: Jiwoo Lee Date: Tue, 3 Oct 2023 17:20:17 -0700 Subject: [PATCH 17/19] clean up --- docs/contributing.rst | 6 +++--- docs/index.rst | 1 + 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 44c4c7fd7..886921cd4 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1,8 +1,8 @@ .. highlight:: shell -============ -Contributing -============ +================== +Contributing Guide +================== Contributions are welcome and greatly appreciated! Every little bit helps, and credit will always be given. diff --git a/docs/index.rst b/docs/index.rst index 62ebe58cd..ed1adb90e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -78,6 +78,7 @@ BSD 3-Clause License. See `LICENSE From b05da9d11c7ddeed80620f7c140a4987e056ade5 Mon Sep 17 00:00:00 2001 From: Jiwoo Lee Date: Tue, 3 Oct 2023 17:24:29 -0700 Subject: [PATCH 18/19] add image files --- docs/_static/git-flow.svg | 1 + docs/_static/pre-commit-flow.svg | 1 + 2 files changed, 2 insertions(+) create mode 100644 docs/_static/git-flow.svg create mode 100644 docs/_static/pre-commit-flow.svg diff --git a/docs/_static/git-flow.svg b/docs/_static/git-flow.svg new file mode 100644 index 000000000..593e5149f --- /dev/null +++ b/docs/_static/git-flow.svg @@ -0,0 +1 @@ +
Master
Master
Feature
Feature
Hotfix
Hotfix
v1.0
v1.0
v1.1
v1.1
v1.2
v1.2Viewer does not support full SVG 1.1 \ No newline at end of file diff --git a/docs/_static/pre-commit-flow.svg b/docs/_static/pre-commit-flow.svg new file mode 100644 index 000000000..a0d663061 --- /dev/null +++ b/docs/_static/pre-commit-flow.svg @@ -0,0 +1 @@ +
`git commit -m ....`
`git commit -m ....`
Local Repository
Local Repository
Push
Push
Commit
Commit
Remote Repository
Remote Repository
Success
Success
Fail w/ console output
Fail w/ console output
pre-commit package
pre-commit package
.pre-commit.conf.yaml
.pre-commit.conf.yaml
Trigger build
Trigger build
Create Pull Request
Create Pull Request
CI/CD Workflow Tool (GitHub Actions)
CI/CD Workflow Tool...
workflow.yml
workflow.ymlViewer does not support full SVG 1.1 \ No newline at end of file From bbbee3e7374471678c5adef9a315dc897937add0 Mon Sep 17 00:00:00 2001 From: Jiwoo Lee Date: Tue, 3 Oct 2023 17:34:05 -0700 Subject: [PATCH 19/19] typo fix --- docs/contributing.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 886921cd4..329aa8435 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -177,9 +177,8 @@ Local Development black....................................................................Passed isort....................................................................Passed flake8...................................................................Passed - mypy.....................................................................Passed -11. Commit your changes:: +10. Commit your changes:: $ git add . $ git commit -m @@ -191,16 +190,16 @@ Local Development isort....................................................................Passed flake8...................................................................Passed -12. Make sure pre-commit QA checks pass. Otherwise, fix any caught issues. +11. Make sure pre-commit QA checks pass. Otherwise, fix any caught issues. - Most of the tools fix issues automatically so you just need to re-stage the files. - flake8 and mypy issues must be fixed automatically. -13. Push changes:: +12. Push changes:: $ git push origin -14. Submit a pull request through the GitHub website. +13. Submit a pull request through the GitHub website. Pull Request Guidelines