Flesh out the developer's guide

docs/.gitignore

@@ -14,4 +14,4 @@ design_docs/remapper.rst
 design_docs/template.rst
 design_docs/timekeeping_reorg.rst
 design_docs/variable_mapping_reorg.rst
-quick_start.rst
+/quick_start.rst

docs/developers_guide/docs.rst

@@ -0,0 +1,32 @@
+Building the Documentation
+==========================
+
+With the ``mpas_analysis_dev`` environment activated, you can run:
+
+.. code-block:: bash
+
+    cd docs
+    DOCS_VERSION=test make clean versioned-html
+
+to build the docs locally in the ``_build/html`` subdirectory.
+
+The docs should build cleanly.  If they don't, please attempt to fix the
+errors and warnings even if they are not related to your changes.  We want
+to keep the documentation in good shape.
+
+Previewing the Documentation
+----------------------------
+
+When generating documentation on HPC machines, you will want to copy the html
+output to the public web space to view it, or if the web portal is being
+cranky, scp it to your local machine.
+
+To preview the documentation locally, open the ``index.html`` file in the
+``_build/html/test`` directory with your browser or try:
+
+.. code-block:: bash
+
+    cd _build/html
+    python -m http.server 8000
+
+Then, open http://0.0.0.0:8000/test/ in your browser.

docs/developers_guide/quick_start.rst

@@ -0,0 +1,130 @@
+Quick Start for Developers
+==========================
+
+This guide provides a condensed overview for developers to get started with
+MPAS-Analysis development.
+
+1. Fork and Clone the Repository
+--------------------------------
+- Fork `MPAS-Analysis <https://github.com/MPAS-Dev/MPAS-Analysis>`_ on GitHub.
+- Clone the main repo and your fork locally:
+  - Create a base directory (e.g., ``mpas-analysis``).
+  - Clone the main repo:
+
+    .. code-block:: bash
+
+       git clone git@github.com:MPAS-Dev/MPAS-Analysis.git develop
+
+  - Add your fork as a remote:
+
+    .. code-block:: bash
+
+       git remote add <username>/MPAS-Analysis git@github.com:<username>/MPAS-Analysis.git
+
+2. Configure Git
+----------------
+- Set up your ``~/.gitconfig`` with your name and email (must match your
+  GitHub account).
+- Recommended: set editor, color, and useful aliases.
+
+3. Set Up SSH Keys
+------------------
+- Add SSH keys to GitHub for push access.
+- See: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account
+
+4. Create a Development Worktree
+--------------------------------
+- Fetch latest changes:
+
+    .. code-block:: bash
+
+       git fetch --all -p
+
+- Create a worktree for your feature branch:
+
+    .. code-block:: bash
+
+       git worktree add ../<feature_branch>
+
+- Enter the worktree directory:
+
+    .. code-block:: bash
+
+       cd ../<feature_branch>
+
+5. Set Up Conda Environment
+---------------------------
+- Install Miniforge3 (recommended) or Miniconda.
+- For Miniconda, add ``conda-forge`` channel and set strict priority.
+- Create environment:
+
+    .. code-block:: bash
+
+       conda create -y -n mpas_analysis_dev --file dev-spec.txt
+
+- Activate:
+
+    .. code-block:: bash
+
+       conda activate mpas_analysis_dev
+
+- Install MPAS-Analysis in edit mode:
+
+    .. code-block:: bash
+
+       python -m pip install --no-deps --no-build-isolation -e .
+
+6. Activate Environment (each session)
+--------------------------------------
+- For bash:
+
+    .. code-block:: bash
+
+       source ~/miniforge3/etc/profile.d/conda.sh; conda activate mpas_analysis_dev
+
+- For csh:
+
+    .. code-block:: csh
+
+       source ~/miniforge3/etc/profile.d/conda.csh; conda activate mpas_analysis_dev
+
+7. Configure and Run MPAS-Analysis
+----------------------------------
+- Copy and edit a config file (e.g., ``example_e3sm.cfg``) for your run.
+- Set required options: ``mainRunName``, ``baseDirectory``, ``mpasMeshName``, output paths.
+- Set ``mapMpiTasks = 1`` and ``mapParallelExec = None`` for development environments.
+- Export HDF5 file locking variable if needed:
+  - Bash:
+
+    .. code-block:: bash
+
+       export HDF5_USE_FILE_LOCKING=FALSE
+
+  - Csh:
+
+    .. code-block:: csh
+
+       setenv HDF5_USE_FILE_LOCKING FALSE
+
+- Run analysis:
+
+    .. code-block:: bash
+
+       mpas_analysis -m <machine> <your_config>.cfg
+
+8. View Results
+---------------
+- Output is a set of web pages in your specified output directory.
+- On some systems, update permissions:
+
+    .. code-block:: bash
+
+       chmod -R ugo+rX <output_dir>
+
+- See the main web page for links to results and provenance info.
+
+Additional Recommendations
+--------------------------
+- Use VS Code for remote editing and linting (optional).
+
+For more details, see the full :doc:`../tutorials/dev_getting_started`.

docs/developers_guide/releasing.rst

@@ -0,0 +1,95 @@
+.. _dev_releasing:
+
+***********************
+Releasing a New Version
+***********************
+
+This document describes the steps for maintainers to tag and release a new
+version of ``MPAS-Analysis``, and to update the conda-forge feedstock.
+
+Version Bump and Dependency Updates
+===================================
+
+1. **Update the Version Number**
+
+   - Open a pull request (PR) to update the version number in the following
+     two files:
+
+     - ``mpas_analysis/version.py``
+
+     - ``ci/recipe/meta.yaml``
+
+   - Make sure the version follows `semantic versioning <https://semver.org/>`_.
+
+2. **Check and Update Dependencies**
+
+   - Ensure that dependencies and their constraints are up-to-date and
+     consistent in:
+
+     - ``ci/recipe/meta.yaml`` (dependencies for the conda-forge release)
+
+     - ``pyproject.toml`` (dependencies for PyPI; used as a sanity check)
+
+     - ``dev-spec.txt`` (development dependencies; should be a superset of
+       those for the conda-forge release)
+
+   - The dependencies in ``meta.yaml`` are the ones that will be used for the
+     released package on conda-forge. The dependencies in ``pyproject.toml``
+     are for PyPI and should be kept in sync as much as possible but are only
+     there as a sanity check when we run ``pip check``. The ``dev-spec.txt``
+     file should include all dependencies needed for development and testing.
+
+   - Review and update dependency versions and constraints as needed.
+
+3. **Make a PR and merge it**
+
+Tagging and Publishing a Release
+================================
+
+4. **Tag the Release on GitHub**
+
+   - Go to https://github.com/MPAS-Dev/MPAS-Analysis/releases and click on
+     "Draft a new release".
+
+   - Enter the appropriate tag for the release, following semantic versioning
+     (e.g., ``1.13.0``; **do not** include a ``v`` in front).
+
+   - Enter a release title (typically the release version **with** a ``v`` in
+     front, e.g., ``v1.13.0``).
+
+   - Write a description and/or use the "Generate release notes" button to
+     auto-generate release notes.
+
+   - If the release is ready, click "Publish release". Otherwise, save it as a
+     draft.
+
+Updating the conda-forge Feedstock
+==================================
+
+5. **Update the conda-forge Feedstock**
+
+   - After the release is published, update and merge a PR for the new release
+     at the conda-forge feedstock:
+     https://github.com/conda-forge/mpas-analysis-feedstock
+
+   - The conda-forge bot should automatically create a pull request for the
+     new version within a few hours to a day after the release.
+
+   - Compare the dependencies in the new release to those in the previous
+     release and update the recipe as needed. To do this:
+
+     - Find the most recent release at
+       https://github.com/MPAS-Dev/MPAS-Analysis/releases
+
+     - Use the "Compare" feature to select the previous release.
+
+     - Under "changed files", locate ``ci/recipe/meta.yaml`` to see
+       any dependency changes.
+
+   - Review and update the feedstock PR as needed, then merge it.
+
+   - If you are not already a maintainer of the feedstock, you can request to
+     be added by creating a new issue at
+     https://github.com/conda-forge/mpas-analysis-feedstock/issues, choosing
+     "Bot command", and putting
+     ``@conda-forge-admin, please add user @username`` as the subject.