Contributing

Contributions are welcome and greatly appreciated! Every little bit helps, and credit will always be given.

Types of Contributions

xCDAT includes issue templates based on the contribution type: https://github.com/xCDAT/xcdat/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:

Feature is not implemented by xarray
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
Feature is not limited to specific use cases (e.g., data quality issues)
Feature is generally reusable
Feature is relatively simple and lightweight to implement and use

Documentation Update

Help improve xCDAT'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.

Version Control

The repository uses branch-based (core team) and fork-based (external collaborators) Git workflows with tagged software releases.

Guidelines

main must always be deployable
All changes are made through support branches
Rebase with the latest main to avoid/resolve conflicts
Make sure pre-commit quality assurance checks pass when committing (enforced in CI/CD build)
Open a pull request early for discussion
Once the CI/CD build passes and pull request is approved, squash and rebase your commits
Merge pull request into main and delete the branch

Things to Avoid

Don't merge in broken or commented out code
Don't commit directly to main
- There are branch-protection rules for main
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.

pre-commit Flow

Get Started

Ready to contribute? Here's how to set up xCDAT 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

xCDAT includes a VS Code workspace file (.vscode/xcdat.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

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

Fork the xcdat repo on GitHub.
- If you are a maintainer, you can clone and branch directly from the root repository here: https://github.com/xCDAT/xcdat

Clone your fork locally:

$ git clone git@github.com:your_name_here/xcdat.git

<OPTIONAL> Open .vscode/xcdat.code-settings in VS Code

Create and activate Conda development environment:

$ cd xcdat
$ conda env create -f conda-env/dev.yml
$ conda activate xcdat_dev

<OPTIONAL> Set VS Code Python interpretor to xcdat_dev

Install pre-commit:

$ pre-commit install
pre-commit installed at .git/hooks/pre-commit

Create a branch for local development and make changes:
```
$ git checkout -b <BRANCH-NAME>
```

<OPTIONAL> 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

Generate code coverage report and check unit tests pass:

$ make test # Automatically opens HTML report in your browser
$ pytest # Does not automatically open HTML report in your browser

================================= test session starts =================================
platform darwin -- Python 3.8.8, pytest-6.2.2, py-1.10.0, pluggy-0.13.1
rootdir: <your-local-dir/xcdat>, configfile: setup.cfg
plugins: anyio-2.2.0, cov-2.11.1
collected 3 items

tests/test_dataset.py ..
tests/test_xcdat.py .

---------- coverage: platform darwin, python 3.8.8-final-0 -----------
Name                Stmts   Miss  Cover
---------------------------------------
xcdat/__init__.py       3      0   100%
xcdat/dataset.py       18      0   100%
xcdat/xcdat.py          0      0   100%
---------------------------------------
TOTAL                  21      0   100%
Coverage HTML written to dir tests_coverage_reports/htmlcov
Coverage XML written to file tests_coverage_reports/coverage.xml

The Coverage HTML report is much more detailed (e.g., exact lines of tested/untested code)

Commit your changes:

$ git add .
$ git commit -m <Your detailed description of your changes>

Trim Trailing Whitespace.................................................Passed
Fix End of Files.........................................................Passed
Check Yaml...............................................................Passed
black....................................................................Passed
isort....................................................................Passed
flake8...................................................................Passed
mypy.....................................................................Passed

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.
Push changes:
```
$ git push origin <BRANCH-NAME>
```
Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

The pull request should include tests for new or modified code.
Link issues to pull requests.
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.
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

xCDAT integrates the Black code formatter for code styling. If you want to learn more, please read about it here.

xCDAT 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 xCDAT 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:

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

Helpful Commands

Note

Run make help in the root of the project for a list of useful commands

To run a subset of tests:

$ pytest tests.test_xcdat

FAQs

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

<OPTIONAL if you are forking> 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
Get the SHA of the commit OR number of commits to rebase to
git checkout <branch-name>
git log --graph --decorate --pretty=oneline --abbrev-commit
Squash commits:
git rebase -i [SHA]

# OR

git rebase -i HEAD~[NUMBER OF COMMITS]
Rebase branch onto main
git rebase main
git push -f origin <BRANCH-NAME>
Make sure your squashed commit messages are refined
Force push to remote branch
git push -f origin <BRANCH-NAME>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing

Types of Contributions

Bug Report

Feature Request

Documentation Update

Community Discussion

Version Control

Guidelines

Things to Avoid

Pre-commit

Get Started

VS Code, the editor of choice

VS Code Setup

Recommended VS Code Extensions

Local Development

Pull Request Guidelines

Style Guide

Testing

DOs for Testing

DON'Ts for Testing

Documenting Code

DOs for Documenting Code

DON'Ts for Documenting Code

Developer Tips

Helpful Commands

FAQs

Why squash and rebase commits?

How do I squash and rebase commits?

FilesExpand file tree

CONTRIBUTING.rst

Latest commit

History

CONTRIBUTING.rst

File metadata and controls

Contributing

Types of Contributions

Bug Report

Feature Request

Documentation Update

Community Discussion

Version Control

Guidelines

Things to Avoid

Pre-commit

Get Started

VS Code, the editor of choice

VS Code Setup

Recommended VS Code Extensions

Local Development

Pull Request Guidelines

Style Guide

Testing

DOs for Testing

DON'Ts for Testing

Documenting Code

DOs for Documenting Code

DON'Ts for Documenting Code

Developer Tips

Helpful Commands

FAQs

Why squash and rebase commits?

How do I squash and rebase commits?