Merge pull request #272 from iiasa/enh/codeowners

Add initial code owners

Author: khaeru

.github/CODEOWNERS

@@ -0,0 +1,40 @@
+# Notes
+# - No owner is assigned for "*". This means that changes to
+#   all other files can be approved by any user with write
+#   access to the repo.
+
+# Includes this file, GitHub Actions workflows, and more
+/.github  @khaeru @glatterf42
+
+/doc/api/tools-costs.rst              @measrainsey
+/message_ix_models/data/costs         @measrainsey
+/message_ix_models/data/intratec      @measrainsey
+/message_ix_models/tests/tools/costs  @measrainsey
+/message_ix_models/tools/costs        @measrainsey
+
+/doc/material                            @GamzeUnlu95 @macflo8
+/message_ix_models/data/material         @GamzeUnlu95 @macflo8
+/message_ix_models/model/material        @GamzeUnlu95 @macflo8
+/message_ix_models/tests/model/material  @GamzeUnlu95 @macflo8
+
+/doc/transport
+/message_ix_models/data/transport         @khaeru @r-aneeque
+/message_ix_models/model/transport        @khaeru @r-aneeque
+/message_ix_models/tests/model/transport  @khaeru @r-aneeque
+
+/doc/water                            @adrivinca @awais307
+/message_ix_models/data/water         @adrivinca @awais307
+/message_ix_models/model/water        @adrivinca @awais307
+/message_ix_models/tests/model/water  @adrivinca @awais307
+
+# /message_ix_models/project/advance
+# /message_ix_models/project/circeular
+# /message_ix_models/project/edits
+# /message_ix_models/project/engage
+# /message_ix_models/project/gea
+
+/doc/project/navigate.rst            @khaeru
+/message_ix_models/project/navigate  @khaeru
+
+# /message_ix_models/project/shape
+# /message_ix_models/project/ssp

doc/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= --jobs=auto
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build

doc/develop.rst

@@ -46,6 +46,43 @@ Code that will only work with certain structures…
 Code **may** also check a :class:`.Context` instance and automatically adapt data from certain structures to others, e.g. by interpolating data for certain periods or areas.
 To help with validation, code that does this **should** log on the :data:`logging.INFO` level to advertise these steps.
 
+.. _code-owners:
+
+Code owners
+===========
+
+The file :file:`.github/CODEOWNERS` (`on GitHub <https://github.com/iiasa/message-ix-models/blob/main/.github/CODEOWNERS>`__) indicates ‘owners’ for some files in the repository.
+See `GitHub's documentation of this feature <https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners>`__.
+For :mod:`message_ix_models`, we use this to designate people who are capable and responsible to evaluate whether changes in a pull request would have any impact on current or planned research applications of that code, and to suggest whether and how to adjust PRs.
+
+- As of 2025-01-10, we **do not require** pull request approvals from code owners on every PR that modifies files they own.
+  Owners only are notified of such PRs.
+  The author of a PR **should**:
+
+  - Observe the notified owners, if any.
+  - In the "How to review" section of the PR template, address those people individually with what (if anything) they need to look at as part of the PR.
+    This **may** entail saying, "@owner-a @owner-b: no need to review because <reasons>".
+
+- Groups of entries **should** include paths to all of the following, where applicable:
+
+  - Documentation, for instance :file:`/doc/{name}` or :file:`/doc/project/{name}.rst`
+  - Data, for instance :file:`/message_ix_models/data/{name}`
+  - Code, for instance :file:`/message_ix_models/model/{name}` or :file:`/message_ix_models/project/{name}`
+  - Tests, for instance :file:`/message_ix_models/tests/model/{name}` or :file:`/message_ix_models/tests/project/{name}`.
+
+- At least 2 people (individually, or via a GitHub team) **should** be designated owners for any file.
+  This may include one ‘active’ owner and a ‘backup’, or two or more active owners, etc.
+
+- For any pull request thats add new files to :mod:`message_ix_models`, the author(s) and reviewer(s) **should**:
+
+  - Consider whether the new files have an identifiable owner.
+    This may not be the case, for instance for general-purpose utility code.
+  - Check whether this understanding aligns with the ownership expressed in :file:`CODEOWNERS`.
+  - Add, remove, or adjust entries accordingly.
+  - Describe these changes in commit message(s) or their PR description.
+
+- If code owners depart IIASA or are reassigned to other work, they or the :mod:`message_ix_models` maintainers **must** initiate a discussion to identify a new set of owners for their files.
+
 .. _policy-upstream-versions:
 
 Upstream version policy

doc/whatsnew.rst

@@ -8,6 +8,7 @@ Next release
 - Support for Python 3.8 is dropped (:pull:`250`), as it has reached end-of-life.
 - Expand :doc:`repro` with sections on :ref:`repro-doc` and :ref:`versioning`, including :ref:`a list of external model names and ‘versions’ <model-names>` like “MESSAGEix-GLOBIOM 2.0” (:issue:`224`, :pull:`226`).
 - New code list :ref:`emission-yaml` (:pull:`225`).
+- Designate :ref:`code-owners` for certain files (:pull:`272`) and document development practices.
 
 By topic: