Skip to content

Commit 82fe1cd

Browse files
xylarxylar
committed
Flesh out the developer's guide
This includes: * adding a quick start for developers * adding a note on building the documentation * documenting the test suites * notes on how to make releases
1 parent 239549b commit 82fe1cd

6 files changed

Lines changed: 411 additions & 1 deletion

File tree

‎docs/.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,4 @@ design_docs/remapper.rst
1414
design_docs/template.rst
1515
design_docs/timekeeping_reorg.rst
1616
design_docs/variable_mapping_reorg.rst
17-
quick_start.rst
17+
/quick_start.rst

‎docs/developers_guide/docs.rst‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
Building the Documentation
2+
==========================
3+
4+
With the ``mpas_analysis_dev`` environment activated, you can run:
5+
6+
.. code-block:: bash
7+
8+
cd docs
9+
DOCS_VERSION=test make clean versioned-html
10+
11+
to build the docs locally in the ``_build/html`` subdirectory.
12+
13+
The docs should build cleanly. If they don't, please attempt to fix the
14+
errors and warnings even if they are not related to your changes. We want
15+
to keep the documentation in good shape.
16+
17+
Previewing the Documentation
18+
----------------------------
19+
20+
When generating documentation on HPC machines, you will want to copy the html
21+
output to the public web space to view it, or if the web portal is being
22+
cranky, scp it to your local machine.
23+
24+
To preview the documentation locally, open the ``index.html`` file in the
25+
``_build/html/test`` directory with your browser or try:
26+
27+
.. code-block:: bash
28+
29+
cd _build/html
30+
python -m http.server 8000
31+
32+
Then, open http://0.0.0.0:8000/test/ in your browser.

‎docs/developers_guide/quick_start.rst‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
Quick Start for Developers
2+
==========================
3+
4+
This guide provides a condensed overview for developers to get started with
5+
MPAS-Analysis development.
6+
7+
1. Fork and Clone the Repository
8+
--------------------------------
9+
- Fork `MPAS-Analysis <https://github.com/MPAS-Dev/MPAS-Analysis>`_ on GitHub.
10+
- Clone the main repo and your fork locally:
11+
- Create a base directory (e.g., ``mpas-analysis``).
12+
- Clone the main repo:
13+
14+
.. code-block:: bash
15+
16+
git clone git@github.com:MPAS-Dev/MPAS-Analysis.git develop
17+
18+
- Add your fork as a remote:
19+
20+
.. code-block:: bash
21+
22+
git remote add <username>/MPAS-Analysis git@github.com:<username>/MPAS-Analysis.git
23+
24+
2. Configure Git
25+
----------------
26+
- Set up your ``~/.gitconfig`` with your name and email (must match your
27+
GitHub account).
28+
- Recommended: set editor, color, and useful aliases.
29+
30+
3. Set Up SSH Keys
31+
------------------
32+
- Add SSH keys to GitHub for push access.
33+
- See: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account
34+
35+
4. Create a Development Worktree
36+
--------------------------------
37+
- Fetch latest changes:
38+
39+
.. code-block:: bash
40+
41+
git fetch --all -p
42+
43+
- Create a worktree for your feature branch:
44+
45+
.. code-block:: bash
46+
47+
git worktree add ../<feature_branch>
48+
49+
- Enter the worktree directory:
50+
51+
.. code-block:: bash
52+
53+
cd ../<feature_branch>
54+
55+
5. Set Up Conda Environment
56+
---------------------------
57+
- Install Miniforge3 (recommended) or Miniconda.
58+
- For Miniconda, add ``conda-forge`` channel and set strict priority.
59+
- Create environment:
60+
61+
.. code-block:: bash
62+
63+
conda create -y -n mpas_analysis_dev --file dev-spec.txt
64+
65+
- Activate:
66+
67+
.. code-block:: bash
68+
69+
conda activate mpas_analysis_dev
70+
71+
- Install MPAS-Analysis in edit mode:
72+
73+
.. code-block:: bash
74+
75+
python -m pip install --no-deps --no-build-isolation -e .
76+
77+
6. Activate Environment (each session)
78+
--------------------------------------
79+
- For bash:
80+
81+
.. code-block:: bash
82+
83+
source ~/miniforge3/etc/profile.d/conda.sh; conda activate mpas_analysis_dev
84+
85+
- For csh:
86+
87+
.. code-block:: csh
88+
89+
source ~/miniforge3/etc/profile.d/conda.csh; conda activate mpas_analysis_dev
90+
91+
7. Configure and Run MPAS-Analysis
92+
----------------------------------
93+
- Copy and edit a config file (e.g., ``example_e3sm.cfg``) for your run.
94+
- Set required options: ``mainRunName``, ``baseDirectory``, ``mpasMeshName``, output paths.
95+
- Set ``mapMpiTasks = 1`` and ``mapParallelExec = None`` for development environments.
96+
- Export HDF5 file locking variable if needed:
97+
- Bash:
98+
99+
.. code-block:: bash
100+
101+
export HDF5_USE_FILE_LOCKING=FALSE
102+
103+
- Csh:
104+
105+
.. code-block:: csh
106+
107+
setenv HDF5_USE_FILE_LOCKING FALSE
108+
109+
- Run analysis:
110+
111+
.. code-block:: bash
112+
113+
mpas_analysis -m <machine> <your_config>.cfg
114+
115+
8. View Results
116+
---------------
117+
- Output is a set of web pages in your specified output directory.
118+
- On some systems, update permissions:
119+
120+
.. code-block:: bash
121+
122+
chmod -R ugo+rX <output_dir>
123+
124+
- See the main web page for links to results and provenance info.
125+
126+
Additional Recommendations
127+
--------------------------
128+
- Use VS Code for remote editing and linting (optional).
129+
130+
For more details, see the full :doc:`../tutorials/dev_getting_started`.

‎docs/developers_guide/releasing.rst‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
.. _dev_releasing:
2+
3+
***********************
4+
Releasing a New Version
5+
***********************
6+
7+
This document describes the steps for maintainers to tag and release a new
8+
version of ``MPAS-Analysis``, and to update the conda-forge feedstock.
9+
10+
Version Bump and Dependency Updates
11+
===================================
12+
13+
1. **Update the Version Number**
14+
15+
- Open a pull request (PR) to update the version number in the following
16+
two files:
17+
18+
- ``mpas_analysis/version.py``
19+
20+
- ``ci/recipe/meta.yaml``
21+
22+
- Make sure the version follows `semantic versioning <https://semver.org/>`_.
23+
24+
2. **Check and Update Dependencies**
25+
26+
- Ensure that dependencies and their constraints are up-to-date and
27+
consistent in:
28+
29+
- ``ci/recipe/meta.yaml`` (dependencies for the conda-forge release)
30+
31+
- ``pyproject.toml`` (dependencies for PyPI; used as a sanity check)
32+
33+
- ``dev-spec.txt`` (development dependencies; should be a superset of
34+
those for the conda-forge release)
35+
36+
- The dependencies in ``meta.yaml`` are the ones that will be used for the
37+
released package on conda-forge. The dependencies in ``pyproject.toml``
38+
are for PyPI and should be kept in sync as much as possible but are only
39+
there as a sanity check when we run ``pip check``. The ``dev-spec.txt``
40+
file should include all dependencies needed for development and testing.
41+
42+
- Review and update dependency versions and constraints as needed.
43+
44+
3. **Make a PR and merge it**
45+
46+
Tagging and Publishing a Release
47+
================================
48+
49+
4. **Tag the Release on GitHub**
50+
51+
- Go to https://github.com/MPAS-Dev/MPAS-Analysis/releases and click on
52+
"Draft a new release".
53+
54+
- Enter the appropriate tag for the release, following semantic versioning
55+
(e.g., ``1.13.0``; **do not** include a ``v`` in front).
56+
57+
- Enter a release title (typically the release version **with** a ``v`` in
58+
front, e.g., ``v1.13.0``).
59+
60+
- Write a description and/or use the "Generate release notes" button to
61+
auto-generate release notes.
62+
63+
- If the release is ready, click "Publish release". Otherwise, save it as a
64+
draft.
65+
66+
Updating the conda-forge Feedstock
67+
==================================
68+
69+
5. **Update the conda-forge Feedstock**
70+
71+
- After the release is published, update and merge a PR for the new release
72+
at the conda-forge feedstock:
73+
https://github.com/conda-forge/mpas-analysis-feedstock
74+
75+
- The conda-forge bot should automatically create a pull request for the
76+
new version within a few hours to a day after the release.
77+
78+
- Compare the dependencies in the new release to those in the previous
79+
release and update the recipe as needed. To do this:
80+
81+
- Find the most recent release at
82+
https://github.com/MPAS-Dev/MPAS-Analysis/releases
83+
84+
- Use the "Compare" feature to select the previous release.
85+
86+
- Under "changed files", locate ``ci/recipe/meta.yaml`` to see
87+
any dependency changes.
88+
89+
- Review and update the feedstock PR as needed, then merge it.
90+
91+
- If you are not already a maintainer of the feedstock, you can request to
92+
be added by creating a new issue at
93+
https://github.com/conda-forge/mpas-analysis-feedstock/issues, choosing
94+
"Bot command", and putting
95+
``@conda-forge-admin, please add user @username`` as the subject.

0 commit comments

Comments
 (0)