From 0a3d3911db66250f7e49535c2b4e2a2a8b3d4831 Mon Sep 17 00:00:00 2001 From: jiaweizhuang Date: Mon, 5 Aug 2019 21:51:27 -0700 Subject: [PATCH] guide on asking for help and providing support --- doc/index.rst | 51 +++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 41 insertions(+), 10 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index e6225b1..ed27087 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -13,13 +13,12 @@ It is - **Fast**: It is faster than ESMPy's original Fortran regridding engine in serial case (surprise! here's :doc:`benchmark <./Backend>`), and also supports dask_ for `out-of-core, parallel computation `_. -.. note:: - xESMF is at early stage of development and will keep improving in the future. - The major regridding API should be quite stable, - but minor ultilities could change in the next version. - If you find any bugs or would like to request any enhancements, - please `raise an issue on GitHub `_. +.. _ESMF: https://www.earthsystemcog.org/projects/esmf/ +.. _ESMPy: https://www.earthsystemcog.org/projects/esmpy/ +.. _xarray: http://xarray.pydata.org +.. _dask: https://dask.org/ + Contents -------- @@ -63,7 +62,39 @@ Contents user_api internal_api -.. _ESMF: https://www.earthsystemcog.org/projects/esmf/ -.. _ESMPy: https://www.earthsystemcog.org/projects/esmpy/ -.. _xarray: http://xarray.pydata.org -.. _dask: https://dask.org/ \ No newline at end of file + +How to ask for help +------------------- + +The `GitHub issue tracker `_ is the primary place for bug reports. If you hit any issues, I recommend the following steps: + +- First, `search for existing issues `_. Other people are likely to hit the same problem and probably have already found the solution. + +- For a new bug, please `craft a minimal bug report `_ with reproducible code. Use synthetic data or `upload `_ a small sample of input data (~1 MB) so I can quickly reproducible your error. + +- For platform-dependent problems (such as kernel dying and installation error), please also show how to reproduce your system environment, otherwise I have no way to diagnose the issue. The best approach is probably finding an `official Docker image `_ that is closest to your OS (such as `Ubuntu `_ or `CentOS `_), and build your Python environment starting with such image, to see whether the error still exists. Alternatively you can select from public cloud images, such as `Amazon Machine Images `_ or `Google Cloud Images `_. If the error only happens on your institution's HPC cluster, please contact the system administrator for help. + +For general "how-to" questions that are not bugs, you can also post on `StackOverflow `_ (ref: `xarray questions `_) and send me the link. For small questions also feel free to @ me `on Twitter `_. + + +**The "Don'ts"**: + +- Do not describe your problem in a private email, as this would require me to reply similar emails many times. `Keep all discussions in public places `_ like GitHub or StackOverflow. +- Do not only show the error/problem without providing the steps to reproduce it. +- Do not take screenshots of your code, as they are not copy-pastable. + + +How to support xESMF +-------------------- + +xESMF is so far my personal unfunded project; most development happens during my (very limited) free time at graduate school. Your support in any form will be appreciated. + +The easy ways (takes several seconds): + +- `Give a star `_ to its `GitHub repository `_. +- Share it via social media like Twitter; introduce it to your friends/advisors/students. + +More advanced ways: + +- Cite xESMF in your scientific publications. Currently the best way is to cite the DOI: https://doi.org/10.5281/zenodo.1134365. +- If you'd like to contribute code, see this `preliminary contributor guide `_. Also see `Contributing to xarray `_ for more backgrounds.