rileyjmurray
commented
1 year ago Here are some notes from our October 17 meeting.
Everyone's on board with the proposal I made above. (Modulo one edit I had to make.)
We'll implement tags concretely with one-line comments before any def to indicate high, low, or minimal exposure.
It's important to note that these markings are kind of our guess at what the community is using. Their shelf-life is limited.
Adding these kinds of tags is the first phase of a three-phase effort. The second phase is to replace comments with things that are more permanent or functional (like prepending an underscore to the names of minimal-exposure functions). The third phase will be to public API. We have no goals for when we start phase two.
We should keep the community appraised of this effort as we go along. We can have an "API Stability" page of the pyGSTi website that explains the purpose of the tags, solicits user input, and gives advance notice on bigger changes we might make.
CC @sserita, @enielse, @coreyostrove
coreyostrove
sserita
jordanh6
pyGSTi is both research software and a tool that's used in "production" QCVV. Its research flavor makes it impractical for us to spend a lot of effort differentiating between a public and a private API. At the same, its role in production code means we need to be judicious about changing pyGSTi in a way that would break users' workflows. These factors combined make it hard for newcomers (like myself) to contribute to pyGSTi. Here's a proposal to help get new contributors un-stuck.
Proposed policy
I suggest the following taxonomy for marking a piece of code's level of "user exposure."
I think everyone is on board with a taxonomy along those lines. However, we didn't discuss how these labels would be used to affect pyGSTi's development. I suggest we use it in the following way.
For now, I'd take "pyGSTi maintainer" to mean @sserita, @coreyostrove, or @enielse.
Note: In the call, we joked a bit about marking certain code as "godforsaken," to signify that we'd like to change it substantially, but we don't quite know how or when to do so. While I think that would be helpful, I don't think we need to figure that out now.
Proposed adoption plan
Over the coming months, the pyGSTi maintainers mark all "high exposure" code. Low- and minimal-exposure code is marked along the way, to the extent possible.
The adoption process will effectively complete when we're comfortable with implicitly designating unlabeled code as "minimal exposure." API changes to any such code only require the approval of one maintainer, but the approving maintainer has a responsibility to think about whether or not the code actually has minimal user exposure.
Request to pyGSTi developers
Comment below indicating if you agree with this general direction, or if you'd like changes. Once we converge on what we want to do, we can figure out how exactly we'll do it.