Clarifications in contributors guide (#7595)

* update links to issue labels

* clarify that we actually use ruff now in pre-commit

* mention absolufy-imports which we use in pre-commit

* checked that example test file works

* fix formatting of nested bullets

* add pre-commit to docs env

* clarify which environment to use for docstrings

* explain how to view local html docs build

* clarify what pip -e does

* update git commit message requirements

* clarify that small changes don't require local testing

* whatsnew

* point to CI build of the docs

* add suggestion to use github desktop

* image to help find view docs button on readthedocs

* update outdated screenshot of green ci

* internal link to point to where you can view RTD build

* Add ruff as separate entry in list of pre-commit checks

Co-authored-by: Deepak Cherian <dcherian@users.noreply.github.com>

---------

Co-authored-by: Deepak Cherian <dcherian@users.noreply.github.com>

Author: TomNicholas

ci/requirements/doc.yml

@@ -23,6 +23,7 @@ dependencies:
   - pandas>=1.4
   - pooch
   - pip
+  - pre-commit
   - pyproj
   - rasterio>=1.1
   - scipy!=1.10.0

doc/_static/ci.png

@@ -19,14 +19,14 @@ enhancements, and ideas are welcome.
 If you are brand new to *xarray* or open-source development, we recommend going
 through the `GitHub "issues" tab <https://github.com/pydata/xarray/issues>`_
 to find issues that interest you. There are a number of issues listed under
-`Documentation <https://github.com/pydata/xarray/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation>`_
+`Documentation <https://github.com/pydata/xarray/labels/topic-documentation>`_
 and `good first issue
-<https://github.com/pydata/xarray/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22>`_
+<https://github.com/pydata/xarray/labels/contrib-good-first-issue>`_
 where you could start out. Once you've found an interesting issue, you can
 return here to get your development environment setup.
 
 Feel free to ask questions on the `mailing list
-<https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!forum/xarray>`_.
+<https://groups.google.com/g/xarray>`_.
 
 .. _contributing.bug_reports:
 
@@ -106,6 +106,12 @@ Getting started with Git
 setting up your SSH key, and configuring git.  All these steps need to be completed before
 you can work seamlessly between your local repository and GitHub.
 
+.. note::
+
+    The following instructions assume you want to learn how to interact with github via the git command-line utility,
+    but contributors who are new to git may find it easier to use other tools instead such as
+    `Github Desktop <https://desktop.github.com/>`_.
+
 .. _contributing.forking:
 
 Forking
@@ -122,17 +128,58 @@ want to clone your fork to your machine::
 This creates the directory `xarray` and connects your repository to
 the upstream (main project) *xarray* repository.
 
+Creating a branch
+-----------------
+
+You want your ``main`` branch to reflect only production-ready code, so create a
+feature branch before making your changes. For example::
+
+    git branch shiny-new-feature
+    git checkout shiny-new-feature
+
+The above can be simplified to::
+
+    git checkout -b shiny-new-feature
+
+This changes your working directory to the shiny-new-feature branch.  Keep any
+changes in this branch specific to one bug or feature so it is clear
+what the branch brings to *xarray*. You can have many "shiny-new-features"
+and switch in between them using the ``git checkout`` command.
+
+To update this branch, you need to retrieve the changes from the ``main`` branch::
+
+    git fetch upstream
+    git merge upstream/main
+
+This will combine your commits with the latest *xarray* git ``main``.  If this
+leads to merge conflicts, you must resolve these before submitting your pull
+request.  If you have uncommitted changes, you will need to ``git stash`` them
+prior to updating.  This will effectively store your changes, which can be
+reapplied after updating.
+
 .. _contributing.dev_env:
 
 Creating a development environment
 ----------------------------------
 
-To test out code changes, you'll need to build *xarray* from source, which
+To test out code changes locally, you'll need to build *xarray* from source, which
 requires a Python environment. If you're making documentation changes, you can
 skip to :ref:`contributing.documentation` but you won't be able to build the
 documentation locally before pushing your changes.
 
-.. _contributiong.dev_python:
+.. note::
+
+    For small changes, such as fixing a typo, you don't necessarily need to build and test xarray locally.
+    If you make your changes then :ref:`commit and push them to a new branch <contributing.changes>`,
+    xarray's automated :ref:`continuous integration tests <contributing.ci>` will run and check your code in various ways.
+    You can then try to fix these problems by committing and pushing more commits to the same branch.
+
+    You can also avoid building the documentation locally by instead :ref:`viewing the updated documentation via the CI <contributing.pr>`.
+
+    To speed up this feedback loop or for more complex development tasks you should build and test xarray locally.
+
+
+.. _contributing.dev_python:
 
 Creating a Python Environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -193,35 +240,6 @@ To return to your root environment::
 
 See the full conda docs `here <http://conda.pydata.org/docs>`__.
 
-Creating a branch
------------------
-
-You want your ``main`` branch to reflect only production-ready code, so create a
-feature branch before making your changes. For example::
-
-    git branch shiny-new-feature
-    git checkout shiny-new-feature
-
-The above can be simplified to::
-
-    git checkout -b shiny-new-feature
-
-This changes your working directory to the shiny-new-feature branch.  Keep any
-changes in this branch specific to one bug or feature so it is clear
-what the branch brings to *xarray*. You can have many "shiny-new-features"
-and switch in between them using the ``git checkout`` command.
-
-To update this branch, you need to retrieve the changes from the ``main`` branch::
-
-    git fetch upstream
-    git merge upstream/main
-
-This will combine your commits with the latest *xarray* git ``main``.  If this
-leads to merge conflicts, you must resolve these before submitting your pull
-request.  If you have uncommitted changes, you will need to ``git stash`` them
-prior to updating.  This will effectively store your changes, which can be
-reapplied after updating.
-
 .. _contributing.documentation:
 
 Contributing to the documentation
@@ -302,6 +320,7 @@ Requirements
 ~~~~~~~~~~~~
 Make sure to follow the instructions on :ref:`creating a development environment above <contributing.dev_env>`, but
 to build the docs you need to use the environment file ``ci/requirements/doc.yml``.
+You should also use this environment and these steps if you want to view changes you've made to the docstrings.
 
 .. code-block:: sh
 
@@ -312,7 +331,7 @@ to build the docs you need to use the environment file ``ci/requirements/doc.yml
     # or with older versions of Anaconda:
     source activate xarray-docs
 
-    # Build and install xarray
+    # Build and install a local, editable version of xarray
     pip install -e .
 
 Building the documentation
@@ -323,7 +342,17 @@ To build the documentation run::
     cd doc/
     make html
 
-Then you can find the HTML output in the folder ``xarray/doc/_build/html/``.
+Then you can find the HTML output files in the folder ``xarray/doc/_build/html/``.
+
+To see what the documentation now looks like with your changes, you can view the HTML build locally by opening the files in your local browser.
+For example, if you normally use Google Chrome as your browser, you could enter::
+
+    google-chrome _build/html/quick-overview.html
+
+in the terminal, running from within the ``doc/`` folder.
+You should now see a new tab pop open in your local browser showing the ``quick-overview`` page of the documentation.
+The different pages of this local build of the documentation are linked together,
+so you can browse the whole documentation by following links the same way you would on the officially-hosted xarray docs site.
 
 The first time you build the docs, it will take quite a while because it has to run
 all the code examples and build all the generated docstring pages. In subsequent
@@ -362,14 +391,13 @@ Code Formatting
 xarray uses several tools to ensure a consistent code format throughout the project:
 
 - `Black <https://black.readthedocs.io/en/stable/>`_ for standardized
-  code formatting
+  code formatting,
 - `blackdoc <https://blackdoc.readthedocs.io/en/stable/>`_ for
-  standardized code formatting in documentation
-- `Flake8 <http://flake8.pycqa.org/en/latest/>`_ for general code quality
-- `isort <https://github.com/timothycrosley/isort>`_ for standardized order in imports.
-  See also `flake8-isort <https://github.com/gforcada/flake8-isort>`_.
+  standardized code formatting in documentation,
+- `ruff <https://github.com/charliermarsh/ruff/>`_ for code quality checks and standardized order in imports
+- `absolufy-imports <https://github.com/MarcoGorelli/absolufy-imports>`_ for absolute instead of relative imports from different files,
 - `mypy <http://mypy-lang.org/>`_ for static type checking on `type hints
-  <https://docs.python.org/3/library/typing.html>`_
+  <https://docs.python.org/3/library/typing.html>`_.
 
 We highly recommend that you setup `pre-commit hooks <https://pre-commit.com/>`_
 to automatically run all the above tools every time you make a git commit. This
@@ -418,7 +446,7 @@ of xarray, and for developers of other libraries that depend on xarray.
 Testing With Continuous Integration
 -----------------------------------
 
-The *xarray* test suite runs automatically the
+The *xarray* test suite runs automatically via the
 `GitHub Actions <https://docs.github.com/en/free-pro-team@latest/actions>`__,
 continuous integration service, once your pull request is submitted.
 
@@ -480,7 +508,7 @@ the expected correct result::
 Transitioning to ``pytest``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-*xarray* existing test structure is *mostly* classed based, meaning that you will
+*xarray* existing test structure is *mostly* class-based, meaning that you will
 typically find tests wrapped in a class.
 
 .. code-block:: python
@@ -517,8 +545,6 @@ features that we like to use.
 We would name this file ``test_cool_feature.py`` and put in an appropriate place in the
 ``xarray/tests/`` structure.
 
-.. TODO: confirm that this actually works
-
 .. code-block:: python
 
     import pytest
@@ -569,26 +595,27 @@ A test run of this yields
 
 .. code-block:: shell
 
-   ((xarray) $ pytest test_cool_feature.py -v
-    =============================== test session starts ================================
+    ((xarray) $ pytest test_cool_feature.py -v
+    ================================= test session starts ==================================
     platform darwin -- Python 3.10.6, pytest-7.2.0, pluggy-1.0.0 --
     cachedir: .pytest_cache
     plugins: hypothesis-6.56.3, cov-4.0.0
     collected 11 items
 
-    test_cool_feature.py::test_dtypes[int8] PASSED
-    test_cool_feature.py::test_dtypes[int16] PASSED
-    test_cool_feature.py::test_dtypes[int32] PASSED
-    test_cool_feature.py::test_dtypes[int64] PASSED
-    test_cool_feature.py::test_mark[float32] PASSED
-    test_cool_feature.py::test_mark[int16] SKIPPED
-    test_cool_feature.py::test_mark[int32] xfail
-    test_cool_feature.py::test_series[int8] PASSED
-    test_cool_feature.py::test_series[int16] PASSED
-    test_cool_feature.py::test_series[int32] PASSED
-    test_cool_feature.py::test_series[int64] PASSED
+    xarray/tests/test_cool_feature.py::test_dtypes[int8] PASSED                       [  9%]
+    xarray/tests/test_cool_feature.py::test_dtypes[int16] PASSED                      [ 18%]
+    xarray/tests/test_cool_feature.py::test_dtypes[int32] PASSED                      [ 27%]
+    xarray/tests/test_cool_feature.py::test_dtypes[int64] PASSED                      [ 36%]
+    xarray/tests/test_cool_feature.py::test_mark[float32] PASSED                      [ 45%]
+    xarray/tests/test_cool_feature.py::test_mark[int16] SKIPPED (unconditional skip)  [ 54%]
+    xarray/tests/test_cool_feature.py::test_mark[int32] XFAIL (to show how it works)  [ 63%]
+    xarray/tests/test_cool_feature.py::test_series[int8] PASSED                       [ 72%]
+    xarray/tests/test_cool_feature.py::test_series[int16] PASSED                      [ 81%]
+    xarray/tests/test_cool_feature.py::test_series[int32] PASSED                      [ 90%]
+    xarray/tests/test_cool_feature.py::test_series[int64] PASSED                      [100%]
+
 
-    ================== 9 passed, 1 skipped, 1 xfailed in 1.83 seconds ==================
+    ==================== 9 passed, 1 skipped, 1 xfailed in 1.83 seconds ====================
 
 Tests that we have ``parametrized`` are now accessible via the test name, for
 example we could run these with ``-k int8`` to sub-select *only* those tests
@@ -598,10 +625,10 @@ which match ``int8``.
 .. code-block:: shell
 
    ((xarray) bash-3.2$ pytest  test_cool_feature.py  -v -k int8
-   =========================== test session starts ===========================
-    platform darwin -- Python 3.10.6, pytest-7.2.0, pluggy-1.0.0 --
-    cachedir: .pytest_cache
-    plugins: hypothesis-6.56.3, cov-4.0.0
+   ================================== test session starts ==================================
+   platform darwin -- Python 3.10.6, pytest-7.2.0, pluggy-1.0.0 --
+   cachedir: .pytest_cache
+   plugins: hypothesis-6.56.3, cov-4.0.0
    collected 11 items
 
    test_cool_feature.py::test_dtypes[int8] PASSED
@@ -728,9 +755,13 @@ If your code is an enhancement, it is most likely necessary to add usage
 examples to the existing documentation.  This can be done following the section
 regarding documentation :ref:`above <contributing.documentation>`.
 
+.. _contributing.changes:
+
 Contributing your changes to *xarray*
 =====================================
 
+.. _contributing.committing:
+
 Committing your code
 --------------------
 
@@ -751,11 +782,11 @@ Doing 'git status' again should give something like::
     #       modified:   /relative/path/to/file-you-added.py
     #
 
-The following defines how a commit message should be structured:
+The following defines how a commit message should ideally be structured:
 
-    * A subject line with `< 72` chars.
-    * One blank line.
-    * Optionally, a commit message body.
+* A subject line with `< 72` chars.
+* One blank line.
+* Optionally, a commit message body.
 
 Please reference the relevant GitHub issues in your commit message using ``GH1234`` or
 ``#1234``.  Either style is fine, but the former is generally preferred.
@@ -764,6 +795,9 @@ Now you can commit your changes in your local repository::
 
     git commit -m
 
+
+.. _contributing.pushing:
+
 Pushing your changes
 --------------------
 
@@ -788,6 +822,8 @@ like::
 Now your code is on GitHub, but it is not yet a part of the *xarray* project.  For that to
 happen, a pull request needs to be submitted on GitHub.
 
+.. _contributing.review:
+
 Review your code
 ----------------
 
@@ -802,6 +838,8 @@ double check your branch changes against the branch it was based on:
 #. Select the ``base`` and ``compare`` branches, if necessary. This will be ``main`` and
    ``shiny-new-feature``, respectively.
 
+.. _contributing.pr:
+
 Finally, make the pull request
 ------------------------------
 
@@ -819,7 +857,16 @@ release.  To submit a pull request:
 #. Click ``Send Pull Request``.
 
 This request then goes to the repository maintainers, and they will review
-the code. If you need to make more changes, you can make them in
+the code.
+
+If you have made updates to the documentation, you can now see a preview of the updated docs by clicking on "Details" under
+the ``docs/readthedocs.org`` check near the bottom of the list of checks that run automatically when submitting a PR,
+then clicking on the "View Docs" button on the right (not the big green button, the small black one further down).
+
+.. image:: _static/view-docs.png
+
+
+If you need to make more changes, you can make them in
 your branch, add them to a new commit, push them to GitHub, and the pull request
 will automatically be updated.  Pushing them to GitHub again is done by::
 
@@ -829,6 +876,8 @@ This will automatically update your pull request with the latest code and restar
 :ref:`Continuous Integration <contributing.ci>` tests.
 
 
+.. _contributing.delete:
+
 Delete your merged branch (optional)
 ------------------------------------
 
@@ -853,20 +902,22 @@ GitHub. To delete it there do::
     git push origin --delete shiny-new-feature
 
 
+.. _contributing.checklist:
+
 PR checklist
 ------------
 
 - **Properly comment and document your code.** See `"Documenting your code" <https://docs.xarray.dev/en/stable/contributing.html#documenting-your-code>`_.
 - **Test that the documentation builds correctly** by typing ``make html`` in the ``doc`` directory. This is not strictly necessary, but this may be easier than waiting for CI to catch a mistake. See `"Contributing to the documentation" <https://docs.xarray.dev/en/stable/contributing.html#contributing-to-the-documentation>`_.
 - **Test your code**.
 
-    - Write new tests if needed. See `"Test-driven development/code writing" <https://docs.xarray.dev/en/stable/contributing.html#test-driven-development-code-writing>`_.
-    - Test the code using `Pytest <http://doc.pytest.org/en/latest/>`_. Running all tests (type ``pytest`` in the root directory) takes a while, so feel free to only run the tests you think are needed based on your PR (example: ``pytest xarray/tests/test_dataarray.py``). CI will catch any failing tests.
-    - By default, the upstream dev CI is disabled on pull request and push events. You can override this behavior per commit by adding a <tt>[test-upstream]</tt> tag to the first line of the commit message. For documentation-only commits, you can skip the CI per commit by adding a "[skip-ci]" tag to the first line of the commit message.
+  - Write new tests if needed. See `"Test-driven development/code writing" <https://docs.xarray.dev/en/stable/contributing.html#test-driven-development-code-writing>`_.
+  - Test the code using `Pytest <http://doc.pytest.org/en/latest/>`_. Running all tests (type ``pytest`` in the root directory) takes a while, so feel free to only run the tests you think are needed based on your PR (example: ``pytest xarray/tests/test_dataarray.py``). CI will catch any failing tests.
+  - By default, the upstream dev CI is disabled on pull request and push events. You can override this behavior per commit by adding a <tt>[test-upstream]</tt> tag to the first line of the commit message. For documentation-only commits, you can skip the CI per commit by adding a "[skip-ci]" tag to the first line of the commit message.
 
 - **Properly format your code** and verify that it passes the formatting guidelines set by `Black <https://black.readthedocs.io/en/stable/>`_ and `Flake8 <http://flake8.pycqa.org/en/latest/>`_. See `"Code formatting" <https://docs.xarray.dev/en/stablcontributing.html#code-formatting>`_. You can use `pre-commit <https://pre-commit.com/>`_ to run these automatically on each commit.
 
-    - Run ``pre-commit run --all-files`` in the root directory. This may modify some files. Confirm and commit any formatting changes.
+  - Run ``pre-commit run --all-files`` in the root directory. This may modify some files. Confirm and commit any formatting changes.
 
-- **Push your code and** `create a PR on GitHub <https://help.github.com/en/articles/creating-a-pull-request>`_.
+- **Push your code** and `create a PR on GitHub <https://help.github.com/en/articles/creating-a-pull-request>`_.
 - **Use a helpful title for your pull request** by summarizing the main contributions rather than using the latest commit message. If the PR addresses an `issue <https://github.com/pydata/xarray/issues>`_, please `reference it <https://help.github.com/en/articles/autolinked-references-and-urls>`_.

doc/_static/view-docs.png

@@ -60,6 +60,8 @@ Bug fixes
 Documentation
 ~~~~~~~~~~~~~
 
+- Clarify language in contributor's guide (:issue:`7495`, :pull:`7595`)
+  By `Tom Nicholas <https://github.com/TomNicholas>`_.
 
 Internal Changes
 ~~~~~~~~~~~~~~~~