Update documentation to copy tags when forking, so versioning is reasonable (#10576)

jemmajeffree · pre-commit-ci[bot] · web-flow · commit 4d16307039f3 · 2025-07-28T17:21:36.000-07:00
* Update docs to copy tags across in a new fork * Update docs so fetch updates xarray version too * Move "create a development environment" so instructions are chronological * Fix hyperlink * Reroute a hyperlink that went to the pandas docs to the equivalent section of these docs * Tidy wording * Update another link to be internal rather than full url * Reformat a couple of minor points * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Add newline to fix syntax * Add some underscores to make warning go away "WARNING: Duplicate explicit target name: "documentation"" --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
diff --git a/doc/contribute/contributing.rst b/doc/contribute/contributing.rst
@@ -37,7 +37,7 @@ Where to start?
 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.
-Some issues are particularly suited for new contributors by the label `Documentation <https://github.com/pydata/xarray/labels/topic-documentation>`_
+Some issues are particularly suited for new contributors by the label `Documentation <https://github.com/pydata/xarray/labels/topic-documentation>`__
 and `good first issue
 <https://github.com/pydata/xarray/labels/contrib-good-first-issue>`_ where you could start out.
 These are well documented issues, that do not require a deep understanding of the internals of xarray.
@@ -130,6 +130,8 @@ you can work seamlessly between your local repository and GitHub.
     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.dev_workflow:
+
 Development workflow
 ====================
 
@@ -151,107 +153,16 @@ maintainers to see what you've done, and why you did it, we recommend you to fol
    This creates the directory ``xarray`` and connects your repository to
    the upstream (main project) *xarray* repository.
 
-Creating a development environment
-----------------------------------
-
-To test out code changes locally, you'll need to build *xarray* from source, which requires you to
-`create a local development environment <https://docs.xarray.dev/en/stable/contributing.html#contributing-dev-env>`_.
-
-Update the ``main`` branch
---------------------------
-
-First make sure you have followed `Setting up xarray for development
-<https://docs.xarray.dev/en/stable/contributing.html#creating-a-development-environment>`_
-
-Before starting a new set of changes, fetch all changes from ``upstream/main``, and start a new
-feature branch from that. From time to time you should fetch the upstream changes from GitHub: ::
-
-    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.
-
-Create a new feature branch
----------------------------
-
-Create a branch to save your changes, even before you start making changes. You want your
-``main branch`` to contain only production-ready code::
-
-    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.
-
-Generally, you will want to keep your feature branches on your public GitHub fork of xarray. To do this,
-you ``git push`` this new branch up to your GitHub repo. Generally (if you followed the instructions in
-these pages, and by default), git will have a link to your fork of the GitHub repo, called ``origin``.
-You push up to your own fork with: ::
-
-    git push origin shiny-new-feature
-
-In git >= 1.7 you can ensure that the link is correctly set by using the ``--set-upstream`` option: ::
-
-    git push --set-upstream origin shiny-new-feature
-
-From now on git will know that ``shiny-new-feature`` is related to the ``shiny-new-feature branch`` in the GitHub repo.
-
-The editing workflow
---------------------
-
-1. Make some changes
+4. Copy tags across from the xarray repository::
 
-2. See which files have changed with ``git status``. You'll see a listing like this one: ::
+    git fetch --tags upstream
 
-    # On branch shiny-new-feature
-    # Changed but not updated:
-    #   (use "git add <file>..." to update what will be committed)
-    #   (use "git checkout -- <file>..." to discard changes in working directory)
-    #
-    #  modified:   README
-
-3. Check what the actual changes are with ``git diff``.
-
-4. Build the `documentation run <https://docs.xarray.dev/en/stable/contributing.html#building-the-documentation>`_
-for the documentation changes.
-
-`Run the test suite <https://docs.xarray.dev/en/stable/contributing.html#running-the-test-suite>`_ for code changes.
-
-Commit and push your changes
-----------------------------
-
-1. To commit all modified files into the local copy of your repo, do ``git commit -am 'A commit message'``.
-
-2. To push the changes up to your forked repo on GitHub, do a ``git push``.
-
-Open a pull request
--------------------
-
-When you're ready or need feedback on your code, open a Pull Request (PR) so that the xarray developers can
-give feedback and eventually include your suggested code into the ``main`` branch.
-`Pull requests (PRs) on GitHub <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_
-are the mechanism for contributing to xarray's code and documentation.
-
-Enter a title for the set of changes with some explanation of what you've done.
-Follow the PR template, which looks like this. ::
-
-    [ ]Closes #xxxx
-    [ ]Tests added
-    [ ]User visible changes (including notable bug fixes) are documented in whats-new.rst
-    [ ]New functions/methods are listed in api.rst
-
-Mention anything you'd like particular attention for - such as a complicated change or some code you are not happy with.
-If you don't think your request is ready to be merged, just say so in your pull request message and use
-the "Draft PR" feature of GitHub. This is a good way of getting some preliminary code review.
+   This will ensure that when you create a development environment a reasonable version number is created.
 
 .. _contributing.dev_env:
 
 Creating a development environment
-==================================
+----------------------------------
 
 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
@@ -281,7 +192,7 @@ development environment:
 - Install either `Anaconda <https://www.anaconda.com/download/>`_ or `miniconda
   <https://conda.io/miniconda.html>`_
 - Make sure your conda is up to date (``conda update conda``)
-- Make sure that you have :ref:`cloned the repository <contributing.forking>`
+- Make sure that you have :ref:`cloned the repository <contributing.dev_workflow>`
 - ``cd`` to the *xarray* source directory
 
 We'll now kick off a two-step process:
@@ -316,7 +227,7 @@ built version:
    $ python  # start an interpreter
    >>> import xarray
    >>> xarray.__version__
-   '0.10.0+dev46.g015daca'
+   '2025.7.2.dev14+g5ce69b2b.d20250725'
 
 This will create the new environment, and not touch any of your existing environments,
 nor any existing Python installation.
@@ -347,6 +258,103 @@ This can be done by running: ::
 from the root of the xarray repository. You can skip the pre-commit checks with
 ``git commit --no-verify``.
 
+
+Update the ``main`` branch
+--------------------------
+
+First make sure you have :ref:`created a development environment <contributing.dev_env>`.
+
+Before starting a new set of changes, fetch all changes from ``upstream/main``, and start a new
+feature branch from that. From time to time you should fetch the upstream changes from GitHub: ::
+
+    git fetch --tags 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.
+
+If the *xarray* ``main`` branch version has updated since you last fetched changes,
+you may also wish to reinstall xarray so that the pip version reflects the *xarray*
+version::
+
+    pip install -e .
+
+Create a new feature branch
+---------------------------
+
+Create a branch to save your changes, even before you start making changes. You want your
+``main branch`` to contain only production-ready code::
+
+    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.
+
+Generally, you will want to keep your feature branches on your public GitHub fork of xarray. To do this,
+you ``git push`` this new branch up to your GitHub repo. Generally (if you followed the instructions in
+these pages, and by default), git will have a link to your fork of the GitHub repo, called ``origin``.
+You push up to your own fork with: ::
+
+    git push origin shiny-new-feature
+
+In git >= 1.7 you can ensure that the link is correctly set by using the ``--set-upstream`` option: ::
+
+    git push --set-upstream origin shiny-new-feature
+
+From now on git will know that ``shiny-new-feature`` is related to the ``shiny-new-feature branch`` in the GitHub repo.
+
+The editing workflow
+--------------------
+
+1. Make some changes
+
+2. See which files have changed with ``git status``. You'll see a listing like this one: ::
+
+    # On branch shiny-new-feature
+    # Changed but not updated:
+    #   (use "git add <file>..." to update what will be committed)
+    #   (use "git checkout -- <file>..." to discard changes in working directory)
+    #
+    #  modified:   README
+
+3. Check what the actual changes are with ``git diff``.
+
+4. Build the `documentation <https://docs.xarray.dev/en/stable/contributing.html#building-the-documentation>`__
+for the documentation changes.
+
+5. `Run the test suite <https://docs.xarray.dev/en/stable/contributing.html#running-the-test-suite>`_ for code changes.
+
+Commit and push your changes
+----------------------------
+
+1. To commit all modified files into the local copy of your repo, do ``git commit -am 'A commit message'``.
+
+2. To push the changes up to your forked repo on GitHub, do a ``git push``.
+
+Open a pull request
+-------------------
+
+When you're ready or need feedback on your code, open a Pull Request (PR) so that the xarray developers can
+give feedback and eventually include your suggested code into the ``main`` branch.
+`Pull requests (PRs) on GitHub <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_
+are the mechanism for contributing to xarray's code and documentation.
+
+Enter a title for the set of changes with some explanation of what you've done.
+Follow the PR template, which looks like this. ::
+
+    [ ]Closes #xxxx
+    [ ]Tests added
+    [ ]User visible changes (including notable bug fixes) are documented in whats-new.rst
+    [ ]New functions/methods are listed in api.rst
+
+Mention anything you'd like particular attention for - such as a complicated change or some code you are not happy with.
+If you don't think your request is ready to be merged, just say so in your pull request message and use
+the "Draft PR" feature of GitHub. This is a good way of getting some preliminary code review.
+
 .. _contributing.documentation:
 
 Contributing to the documentation
@@ -425,7 +433,7 @@ How to build the *xarray* documentation
 
 Requirements
 ~~~~~~~~~~~~
-Make sure to follow the instructions on :ref:`creating a development environment above <contributing.dev_env>`, but
+Make sure to follow the instructions on :ref:`creating a development environment<contributing.dev_env>` above, 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.
 
