search

Pyomo / pyomo

An object-oriented algebraic modeling language in Python for structured optimization problems.
https://www.pyomo.org
Other
2.02k stars 518 forks source link

[PEP] Process for Deprecation and Removal of Pyomo Capabilities #1025

Closed carldlaird closed 1 year ago

carldlaird commented 5 years ago

Proposal

For any functionality that is documented in the Pyomo book, the decision to deprecate or not should be decided by the PMC with a vote. This vote should be held before the PR is merged. Wherever possible, when deprecating code in Pyomo, we should use the deprecation decorators.

Motivation

We want to take care when deprecating functionality and make sure that the entire team is aware of the impact, and that alternative options have been discussed and explored.

whart222 commented 5 years ago

I think this should be generalized to consider changes in pyomo related to online documentation and journal/conference publications as well.

whart222 commented 5 years ago

I'm uncomfortable with the implicit assumption that our APIs are "fixed" after they have been documented. I believe that this will discourage the team from documenting their work, since this provides a penalty for penalty w.r.t. future changes.

We should generalize this PEP to define a mechanism for documenting APIs that we are not committing to supporting long term.

carldlaird commented 5 years ago

I agree that we should not assume that the APIs are fixed. However, I do think we should have a discussion before deprecating functionality that is documented in the Pyomo book. (This does not mean that we won't agree to deprecate - just that a discussion happens.)

Also, I think it is difficult to know ahead of time which APIs you will want to change. I think we need to be more flexible here and discuss it on a case-by-case basis. I don't think I would be able to tell you ahead of time which APIs were "long-term" and which were not.

michaelbynum commented 5 years ago

I think APIs documented in the online docs are less critical than APIs documented in the book because the online docs can be updated quickly and easily (while the book cannot).