Introduce formal principle documentation to support contrib changes

.gitignore

@@ -16,6 +16,7 @@ __pycache__/
 *.egg-info/
 
 # Documentation builds
+doc/OnlineDocs/api
 doc/OnlineDocs/_build
 doc/OnlineDocs/**/*.spy
 

doc/OnlineDocs/contribution_guide.rst

@@ -75,6 +75,32 @@ at least 70% coverage of the lines modified in the PR and prefer coverage
 closer to 90%. We also require that all tests pass before a PR will be 
 merged.
 
+Tests must import the Pyomo test harness from
+``pyomo.common.unittest`` instead of using Python's built-in
+``unittest`` module directly. This wrapper extends the standard testing
+framework with Pyomo-specific capabilities, including automatic plugin
+discovery, solver availability checks, and improved test filtering
+controls. Using the provided interface ensures that all tests run
+consistently across Pyomo's multiple CI environments.
+A small example is shown below:
+
+.. code-block:: python
+
+   import pyomo.common.unittest as unittest
+
+   class TestSomething(unittest.TestCase):
+       def test_basic(self):
+           self.assertEqual(1 + 1, 2)
+
+Developers can also use any of the predefined ``pytest`` markers to categorize
+their tests appropriately.
+Markers are declared in ``pyproject.toml``. Some commonly used markers are:
+
+- ``expensive``: tests that take a long time to run
+- ``mpi``: tests that require MPI
+- ``solver(name)``: dynamic marker to label a test for a specific solver,
+  e.g., ``@pytest.mark.solver("gurobi")``
+
 .. note::
    If you are having issues getting tests to pass on your Pull Request,
    please tag any of the core developers to ask for help.
@@ -336,7 +362,7 @@ Finally, move to the directory containing the clone of your Pyomo fork and run:
 
 ::
 
-  pip install -e .
+  pip install -e .[tests,docs,optional]
 
 These commands register the cloned code with the active python environment
 (``pyomodev``). This way, your changes to the source code for ``pyomo`` are

doc/OnlineDocs/principles.rst

@@ -0,0 +1,218 @@
+Development Principles
+======================
+
+The Pyomo development team follows a set of development principles.
+In order to promote overall transparency, this page is intended to document
+those principles, to the best of our ability, for users and potential
+contributors alike. Please also review Pyomo's recent publication
+on the history of its development for a holistic view into the changes
+of these principles over time [MHJ+25]_.
+
+Backwards Compatibility
+-----------------------
+
+Commitment to Published Interfaces
+++++++++++++++++++++++++++++++++++
+
+If functionality is published in the most recent edition of the
+Pyomo book [PyomoBookIII]_ and corresponding examples, we treat that as
+a public API commitment. Once published in the book, those APIs will not
+change until the next major Pyomo release, which will coincide with a
+new edition of the book.
+
+This commitment ensures that teaching materials, training resources, and
+long-term codebases built on those examples will remain valid across an
+entire major release.
+
+Stable, Supported APIs
+++++++++++++++++++++++
+
+Functionality that is part of the Pyomo source tree but not explicitly
+included in the book is also expected to be stable if it resides outside
+the ``contrib`` (or future ``addons`` / ``devel``) directories.
+
+When changes to these APIs become necessary, we will endeavor to follow one
+(or both) of the following steps:
+
+1. **Deprecation warnings** are added in advance of functionality removal.
+   These are visible to users at import or execution time,
+   with clear guidance on replacement functionality.
+2. **Relocation warnings** are provided for any relocated functionality.
+   These modules import from their old locations and print a warning about
+   the relocation in order to assist users' transition.
+
+Ideally, changes in this fashion can allow users and downstream packages
+to adapt gradually without abrupt breakage.
+
+.. note::
+
+   For detailed guidance on how to mark functionality for deprecation or
+   removal within the Pyomo codebase, see
+   :doc:`/explanation/developer_utils/deprecation`.
+
+Experimental and Contributed Code
++++++++++++++++++++++++++++++++++
+
+Historically, all contributed and experimental functionality has lived
+under ``pyomo.contrib``. These packages are community-driven extensions
+that may evolve rapidly as research and experimentation continue. Users
+should not rely on API stability within this space.
+
+Pyomo is currently transitioning to a clearer organizational model that
+distinguishes between two categories:
+
+* ``pyomo.addons`` – Mostly stable, supported extensions maintained by
+ specific contributors.
+
+* ``pyomo.devel`` – Active research and experimental code.
+
+The guiding philosophy is to protect users from surprises in stable
+interfaces while continuing to enable innovation and experimentation
+in development areas.
+
+Dependency Management
+---------------------
+
+Minimal Core Dependencies
++++++++++++++++++++++++++
+
+Pyomo core is intentionally designed to have only one required
+dependency: ``ply``. This ensures that the base functionality of Pyomo
+can operate using only standard Python libraries and ``ply``.
+
+This approach promotes overall ease of installation, allowing other packages
+to depend and be built upon Pyomo.
+Additionally, this allows users to install and run Pyomo in
+resource-constrained or isolated environments (such as teaching
+containers or HPC systems). All additional packages are optional.
+
+Optional Dependencies
++++++++++++++++++++++
+
+Pyomo supports a number of optional dependencies that enhance its
+functionality. These are grouped into three categories:
+
+* **Tests** – Dependencies needed only to run the automated test suite
+  and continuous integration infrastructure (e.g., ``pytest``,
+  ``parameterized``, ``coverage``).
+
+* **Docs** – Dependencies needed to build the Sphinx-based documentation
+  (e.g., ``sphinx``, ``sphinx_rtd_theme``, ``numpydoc``).
+
+* **Optional** – Dependencies that enable extended
+  functionality throughout the Pyomo codebase, such as numerical
+  computations or data handling (e.g., ``numpy``, ``pandas``,
+  ``matplotlib``).
+
+These optional dependencies can be installed selectively using standard
+``pip`` commands. For example:
+
+::
+
+   pip install pyomo[optional]
+   pip install pyomo[tests,docs]
+
+Pyomo's continuous integration infrastructure regularly tests against
+the most recent versions of all optional dependencies to ensure that
+Pyomo remains compatible with current releases in the Python ecosystem.
+When incompatibilities are identified, the setup configuration is
+updated accordingly.
+
+.. note::
+
+   For more information on installing Pyomo with optional extras,
+   see :doc:`/getting_started/installation`.
+
+Solvers
++++++++
+
+Pyomo does not bundle or directly distribute optimization solvers.
+We recognize that solver installation can be challenging for new users.
+To assist with this process, the documentation includes a solver
+availability table and installation guidance in
+:doc:`/getting_started/solvers`. This table lists solvers that can be
+installed via ``pip`` or ``conda`` where available, but Pyomo itself
+does not include or require any specific solver as a dependency.
+
+
+Contributed Packages
+--------------------
+
+Pyomo has a long history of supporting community-developed extensions.
+Historically, all such contributions were placed under the
+``pyomo.contrib`` namespace. This structure allowed new modeling tools
+and algorithms to be shared quickly, but over time it has become difficult
+for users to distinguish between more stable, supported functionality and
+experimental or research-oriented code.
+
+As a result, Pyomo is transitioning to a more structured contribution
+model with two clear namespaces:
+
+* ``pyomo.addons`` – For mostly stable, supported extensions that build on
+  the Pyomo core. These packages are maintained by dedicated
+  contributors, follow Pyomo's coding and testing standards, and adhere
+  to the same deprecation policies as the rest of the codebase.
+
+* ``pyomo.devel`` – For experimental or rapidly evolving
+  contributions. These modules serve as early experimentation for research ideas,
+  prototypes, or specialized modeling components. Functionality under
+  this namespace may change or be removed between releases without
+  deprecation warnings.
+
+The long-term goal is to provide users and contributors with clearer
+expectations of code maturity and stability. Users can rely on
+``addons`` as stable extensions to Pyomo's core capabilities, while
+``devel`` packages remain a flexible space for experimentation.
+
+.. note::
+
+   For procedural guidance on how to structure and submit new
+   contributions to Pyomo, please visit :doc:`contribution_guide`.
+
+
+Miscellaneous Conventions
+-------------------------
+
+There are a variety of long-standing conventions that have become
+standard across the project. This list will be amended as conventions come
+up, so please refer regularly for updates:
+
+* **Environment imports:** Import the main Pyomo environment as  
+  ``import pyomo.environ as pyo``.  
+  Avoid ``from pyomo.environ import *`` or alternative aliases.
+  Additionally, avoid all uses of ``import *``.
+
+* **Export lists:** Do not define ``__all__`` in modules.  
+  Public symbols are determined by naming and documentation, not explicit lists.
+
+* **Circular imports:** Avoid importing from ``pyomo.core`` into any module
+  in ``pyomo.common`` due to the potential for circular imports.
+
+* **Pull Request naming:** Pull Request titles are added to the CHANGELOG
+  and the release notes. The Pyomo development team reserves the right to
+  alter titles as appropriate to ensure they fit the look and feel of
+  other titles in the CHANGELOG.
+
+* **Full commit history:** We do **not** squash-merge Pull Requests,
+  preferring to retain the entire commit history.
+
+* **URLs:** All links in code, comments, and documentation must use ``https`` 
+  rather than ``http``.
+
+* **File headers:** Every ``.py`` file must begin with the standard Pyomo
+  copyright header:
+
+  .. code-block:: text
+
+     #  ___________________________________________________________________________
+     #
+     #  Pyomo: Python Optimization Modeling Objects
+     #  Copyright (c) 2008-2025
+     #  National Technology and Engineering Solutions of Sandia, LLC
+     #  Under the terms of Contract DE-NA0003525 with National Technology and
+     #  Engineering Solutions of Sandia, LLC, the U.S. Government retains certain
+     #  rights in this software.
+     #  This software is distributed under the 3-clause BSD License.
+     #  ___________________________________________________________________________
+
+  Update the year range as appropriate when modifying files.

doc/OnlineDocs/reference/bibliography.rst

@@ -134,6 +134,12 @@ Bibliography
    Intermediate Relaxations between big-M and Convex Hull
    Reformulations". 2021.  https://arxiv.org/abs/2101.12708
 
+.. [MHJ+25] M. Mundt, W. E. Hart, E. S. Johnson, B. Nicholson, and
+   J. D. Siirola. "Pyomo: Accidentally outrunning the bear", *Patterns*,
+   6(7), 101311. 2025. ISSN 2666-3899. DOI
+   `10.1016/j.patter.2025.101311
+   <https://doi.org/10.1016/j.patter.2025.101311>`_
+
 .. [NW88] G. L. Nemhauser and L. A. Wolsey. *Integer and combinatorial
    optimization*, New York: Wiley. 1988.
 

doc/OnlineDocs/reference/index.rst

@@ -16,6 +16,7 @@ Reference Guides
 .. toctree::
    :maxdepth: 1
 
+   ../principles
    future
    ../errors
    ../related_packages

pyomo/addons/README.md

@@ -0,0 +1,58 @@
+# Pyomo Addons
+
+The `pyomo.addons` directory contains **mostly stable extensions** to Pyomo
+that are **not part of the core library*. These packages extend Pyomo's
+modeling, solver, and analysis capabilities, and have demonstrated sufficient
+maturity, documentation, and testing.
+
+## Purpose
+
+`pyomo.addons` houses packages that:
+
+- Have **mostly stable APIs** suitable for downstream use.
+- Are **sufficiently documented** and **tested**.
+- Represent functionality that is **useful to the wider Pyomo community** but
+  not required for core operation.
+
+Examples include:
+- `gdpopt`
+- `incidence_analysis`
+- `latex_printer`
+- `trustregion`
+- `viewer`
+
+## Requirements
+
+A package may be accepted into `pyomo.addons` once it meets all of the
+following criteria.
+
+### Stability and Maintenance
+- The code must be **mostly stable** with minimal expected API changes.
+- There must be at least one **designated maintainer** responsible for upkeep,
+  compatibility, and user support.
+- The package must not rely on deprecated or experimental Pyomo internals.
+
+### Testing
+- Test coverage should be **at least 80%**, or comparable to similar supported modules.
+- Tests must run successfully within the Pyomo CI environment.
+- Expensive, solver-specific, or optional tests should be properly marked
+  (e.g., with `@pytest.mark.expensive`, `@pytest.mark.solver`).
+
+### Documentation
+- Each addon must include:
+  - (PREFERABLE) A **reference page** in the Pyomo online documentation.
+  - (MINIMUM) A **README.md** file in the addon directory summarizing:
+    - Functionality
+    - Example usage or link to docs
+
+### Dependencies
+- Addons **may not introduce required dependencies** for Pyomo core.
+- Optional dependencies must be:
+  - Declared in `setup.py` under the appropriate category.
+  - Publicly available on PyPI and/or Anaconda and reasonably maintained.
+
+### Backward Compatibility
+- Addons are expected to maintain **backward-compatible APIs** between minor
+  Pyomo releases.
+- Breaking changes must follow the documented **deprecation process** and
+  appear in release notes.

pyomo/devel/README.md

@@ -0,0 +1,48 @@
+# Pyomo Devel
+
+The `pyomo.devel` directory contains **experimental, research-oriented, or
+rapidly evolving** extensions to Pyomo. These packages are **not guaranteed to
+be stable** and may change or be removed between releases **without
+deprecation warnings**.
+
+## Purpose
+
+`pyomo.devel` is intended for:
+
+- Experimental algorithms and modeling approaches.
+- Research prototypes under active development.
+- Functionality that is **not yet ready for long-term API guarantees**.
+- Work that may later graduate into `pyomo.addons` after sufficient
+  maturity, including testing and documentation.
+
+Examples include:
+- `doe`
+- `piecewise`
+- `solver`
+- `sensitivity_toolbox`
+
+## Expectations
+
+Packages placed in `pyomo.devel` are **encouraged to be exploratory** but must
+still meet basic project standards to ensure they do not break the broader
+Pyomo ecosystem.
+
+### Stability
+- APIs in this directory are **not stable** and **may change or be removed**
+  without notice.
+- Users should not rely on `pyomo.devel` components for production workflows.
+
+### Testing
+- All `devel` packages must include **basic tests** verifying import and
+  execution of key components.
+- Tests should run under Pyomo's CI but may be skipped in qualifying scenarios.
+
+### Documentation
+- At minimum, each package should contain:
+  - A **README.md** describing the purpose and experimental status.
+
+### Dependencies
+- Packages in `devel` **may not introduce required dependencies** for Pyomo core.
+- Optional dependencies must be:
+  - Declared in `setup.py` under the appropriate category.
+  - Publicly available on PyPI and/or Anaconda and reasonably maintained.