Merge branch 'feature/improve-documentation' into patch-1-issue-template

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+### Added
+### Changed
+### Deprecated
+### Removed
+### Fixed
+### Security
+
 ## [1.1.0]
 ### Added
 - [commit/4b98808](https://github.com/nasa/ncompare/commit/4b98808cf3d8424da25a226687d304ce7d46738e): Set up dependabot for automated version updates

CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+-   Demonstrating empathy and kindness toward other people
+-   Being respectful of differing opinions, viewpoints, and experiences
+-   Giving and gracefully accepting constructive feedback
+-   Accepting responsibility and apologizing to those affected by our mistakes,
+    and learning from the experience
+-   Focusing on what is best not just for us as individuals, but for the overall
+    community
+
+Examples of unacceptable behavior include:
+
+-   The use of sexualized language or imagery, and sexual attention or advances of
+    any kind
+-   Trolling, insulting or derogatory comments, and personal or political attacks
+-   Public or private harassment
+-   Publishing others' private information, such as a physical or email address,
+    without their explicit permission
+-   Other conduct which could reasonably be considered inappropriate in a
+    professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at [email protected].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from 
+[GESDISC's modified version](https://github.com/nasa/gesdisc-meditor/blob/main/packages/docs/src/pages/code-of-conduct.md) 
+of the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][mozilla coc].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][faq]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[mozilla coc]: https://github.com/mozilla/diversity
+[faq]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -0,0 +1,184 @@
+# Contributing to _ncompare_
+
+Thank you for contributing to _ncompare_!
+
+### Table of Contents
+
+- [How to Contribute](CONTRIBUTING.md#how-to-contribute)
+    - [Reporting Bugs](CONTRIBUTING.md#reporting-bugs)
+    - [Feature Requests](CONTRIBUTING.md#featureenhancement-requests)
+    - [Pull Requests](CONTRIBUTING.md#pull-requests)
+    - [Branches](CONTRIBUTING.md#branches)
+    - [Changelog](CONTRIBUTING.md#changelog)
+    - [Testing](CONTRIBUTING.md#testing)
+    - [Reviewing](CONTRIBUTING.md#reviewing)
+- [Style Guides](CONTRIBUTING.md#style-guides)
+    - [Python Style Guide](CONTRIBUTING.md#python-style-guide)
+    - [Documentation Style Guide](CONTRIBUTING.md#documentation-1)
+
+
+## How to Contribute
+
+### Reporting Bugs
+
+Bugs can be reported by creating a new GitHub issue in this repository. 
+Please use the `bug` label on any bug issue created. Provide detailed 
+instructions on how to reproduce the bug if possible. Include the version 
+of _ncompare_ that produced this bug and specific error messages.
+
+### Feature/Enhancement Requests
+
+Feature/enhancement requests are tracked with GitHub issues. Please use 
+an appropriate label:
+
+- `documentation`
+    - Docstring or documentation changes
+- `automation`
+    - Anything related to CI/CD or metadata
+- `enhancement`
+    - Improvement of an existing feature
+- `new-feature`
+    - An entirely new feature
+
+Feature and enhancement requests should contain a detailed description 
+of the desired behavior and rationale.
+
+### Pull Requests
+
+Please ensure all pull requests follow the PR 
+[template](/.github/pull_request_template.md). This is to ensure
+
+* A reviewer understands what is being changed
+* A reviewer understands why it is being changed
+* A reviewer understands how the changes have been verified
+* A reviewer is confident the changes work as expected and won't break existing functionality.
+
+The name of the pull request should be meaningful, and if the pull 
+request is addressing a GitHub issue, should match the name of the 
+GitHub issue. 
+
+If any performance improvements are being made, please include graphs or charts.
+
+### Branches
+
+- `develop` (protected)
+    - Code actively being developed
+- `main` (protected)
+    - Matches the version currently in prod
+- `release/#.#.#`
+    - Release branch being considered for delivery to prod. 
+    - Matches the version currently in test
+- `feature/issue-#`
+    - Work for enhancements and new features should be done in a branch with this naming convention
+    - The issue number should match the associated GitHub issue number
+- `bugfix/issue-#`
+    - Work for bug fixes should be done in a branch with this naming convention
+    - The issue number should match the associated GitHub issue number
+- `hotfix/issue-#` or `hotfix/short-fix-description`
+    - Rare/special case to address a special anomaly.
+    - The issue number should match the associated GitHub issue number, 
+    unless no such issue exists. If not, use a short description of the 
+    issue e.g. `hotfix/fix-request-url`
+
+### Changelog
+
+_Ncompare_ maintains a [changelog](CHANGELOG.md). See 
+[Keep a Changelog](https://keepachangelog.com/en/1.0.0/) for more 
+information.
+
+The top of the changelog will contain an `[Unreleased]` section. Add 
+any changes made in the current PR to the appropriate section of the 
+changelog.
+
+Please keep changelog messages relatively short (1-2 sentences).
+
+### Testing
+
+In most cases, unit tests should be either created or updated in every PR.
+
+Most Python modules are accompanied by an associated test file named 
+`test_nameofmodule.py`. If resources are needed for unit tests, they 
+should be placed in `tests/data`. Test coverage reports are generated 
+as part of the CI/CD pipeline.
+
+
+### Reviewing
+
+Another valuable way to contribute to the project is to review pull 
+requests. Pull requests reviews are appreciated and valued by anybody 
+at any skill level.
+
+#### Review responsibilities
+
+This list is intended for people conducting code reviews of pull 
+requests. When reviewing a pull request, the reviewer should use the 
+following checklist to verify that the code will not break clients or 
+cause problems; that the code/tests are correct, complete, follow 
+conventions/guidelines, and can be merged into the `main` branch without 
+issue. Some items on the list are very specific, e.g., no TODOs, 
+while others are more open-ended (well-structured tests). The list is 
+intended to make the job of reviewing pull requests easier and more 
+repeatable by identifying areas in pull requests that commonly need 
+addressing. 
+
+When reviewing a pull request, start at the top of the list and consider 
+the most important things that could lead to problems. These are 
+outlined as a set of questions in the Most Important section. Check off 
+the boxes when you are satisfied that each of the criteria is met. Then 
+proceed to the more specific items below in the General, Testing, and 
+Documentation sections.  Check off each box that is satisfied by the 
+pull request and add comments to the pull request for those that are 
+not. If all the boxes are checked, then approve the request. Otherwise, 
+mark it as needing work, or, if there are critical errors, decline it.
+
+#### Most Important (Primum non nocere—"First, do no harm")
+
+- Could this change break clients?
+- Do the changes handle data that may have been previously saved or 
+indexed by an older version of the code?
+- What is the operational impact of this change—are there any 
+potential issues such as special deployment procedures, performance 
+issues, etc.?
+- Are there tests for all cases (including edge cases)?
+- What could go wrong?
+
+#### General
+- Does the code do what it's supposed to do?
+- Have they implemented all the acceptance criteria?
+- There are no overly long or complicated functions that should be 
+broken up for readability
+- Are web API parameters validated?
+- Are symbols used rather than “magic number” constants or string 
+constants? (OK in tests, particularly for error messages or response codes)
+- There is no repeated or copy-and-paste code / tests
+- There are no TODOs
+- There are no stray comment blocks, commented out code, capture/reveals, 
+proto-saves, printlns, or unnecessary logging
+- All namespaces and non-trivial defs/defns/defmacros have docstrings
+- There are no dangling _requires_, i.e., requires that were added and 
+not used or requires that are no longer necessary due to code removal
+- Code conventions are followed
+
+#### Testing
+- If the issue is a bug fix - a test was added that reproduces the 
+conditions that triggered the bug
+- The tests are well-structured and follow current practices
+
+#### Documentation
+- Documentation (api_docs.md, README.md, etc.) was added for any new 
+features or old documentation updated for any changed features
+- Code/curl examples or sample data have been updated as necessary
+- Has the CHANGELOG been updated?
+
+## Style Guides
+
+### Python Style Guide
+
+_Ncompare_ follows PEP8 as much as possible. Reference the _ruff_ and 
+_black_ configuration sections in [pyproject.toml](pyproject.toml) for specific expectations.
+
+### Documentation
+
+_Ncompare_ uses [Numpy docstrings](https://numpydoc.readthedocs.io/en/latest/format.html). 
+All functions should contain a docstring, though short or trivial 
+function may contain a 1-line docstring. 

README.md

@@ -1,6 +1,7 @@
 # ncompare
 _____
 [![Available on pypi](https://img.shields.io/pypi/v/ncompare.svg)](https://pypi.org/project/ncompare/)
+[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/nasa/ncompare/issues)
 [![Formatted with black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
 [![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
 
@@ -57,7 +58,7 @@ poetry run ncompare <netcdf file #1> <netcdf file #2>
 ### Options
 
 - `--file-text` [FILE_PATH]: Text file to write output to.
-- `--file-csv` [FILE_PATH]: Comma separated values (CSV) file to write output to.
+- `--file-csv` [FILE_PATH]: Comma-separated values (CSV) file to write output to.
 - `--file-xlsx` [FILE_PATH]: Excel file to write output to.
 - `--no-color` : Turn off all colorized output.
 - `--show-attributes` : Include variable attributes in the table that compares variables.

ncompare/console.py

@@ -42,7 +42,7 @@ def _cli() -> argparse.Namespace:
 
 
 def main():
-    """Run from command line."""
+    """Run from the command line."""
     args = _cli()
 
     try:

ncompare/core.py

@@ -55,7 +55,7 @@ def compare(
     file_text : str
         filepath destination to save captured text output as a TXT file.
     file_csv : str
-        filepath destination to save comparison output as comma separated values (CSV).
+        filepath destination to save comparison output as comma-separated values (CSV).
     file_xlsx : str
         filepath destination to save comparison output as an Excel workbook.
 
@@ -377,7 +377,7 @@ def _print_var_properties_side_by_side(
         out.side_by_side("chunksize:", v_a.chunking, v_b.chunking, highlight_diff=True)
     # Attributes
     if show_attributes:
-        # Get name of attributes if they exist
+        # Get the name of attributes if they exist
         attrs_a_names = []
         if v_a.attributes:
             attrs_a_names = v_a.attributes.keys()

ncompare/printing.py

@@ -67,7 +67,7 @@ def __init__(
             filepath = Path(text_file)
             if filepath.exists():
                 pass
-            # This will overwrite any existing file at this path, if one exists.
+            # This will overwrite any existing file at this path if one exists.
             self._text_file_obj: Optional[TextIO] = open(
                 filepath, "w", encoding="utf-8"
             )  # pylint: disable=consider-using-with
@@ -118,7 +118,7 @@ def _add_to_history(self, *args):
         """Convert a list of items to a comma-separated string that is added to the csv history."""
 
         def _parse_single_str(s):  # pylint: disable=invalid-name
-            # Remove ANSI escape sequences before adding to parsed string list.
+            # Remove ANSI escape sequences before adding to a parsed string list.
             result = ansi_escape.sub('', s)
             # Remove any leading or trailing newlines.
             return result.strip("\n")