Maintenance and Testing of User Supported Code

All code in core and models is guaranteed to be fully maintained by the core developer team - i.e. if something breaks it is the core developer teams responsibility to fix it. Thus, in order to be included in these folders, the code must be of sufficient quality for the core developer team to be able to maintain without consulting the original developer, and of sufficient general interest that the core developer team is willing to guarantee that it will be maintained (we are a small team and can't maintain everything by ourselves).

The responsibility for maintaining code in the apps and models_extra folders falls primarily upon the users of that code (either the original contributor or later users of the code). Each piece of code should have one or more assigned "code owners" who take responsibility for maintaining the code and who will be called upon to address any issues which arise. The core developer team will take responsibility for notifying the code owners of any issues that are identified (either through failing tests or posted issues) and may assist with fixing any issues, but primary responsibility will fall upon the code owners. If you are using code found in either apps or models_extra, you are strongly encouraged to volunteer to be a code owner in order to ensure that the code you use is fully maintained.

Standards for Contributing User Supported Code

Whilst the standards for accepting contributions of user-supported code are lower than those for code to be included in the core codebase, a minimum set of minimum standards are required to ensure that contributed code is maintainable and of use to other users. In order for a contribution to be accepted as user-supported code, it must meet the following standards:

1. A code owner must be identified who will be responsible for maintaining the code and addressing any test failures or issues that arise in the future.
2. A set of basic unit tests (see Testing Standards) which exercise the main parts of the code (ideally greater than 70% test coverage). These tests are required so that the core developer team can be notified if any changes to the core IDAES code or its dependencies break anything in the user-contributed code.
3. At least one component or integration test that applies the tool or model to a well-defined use case and check that the expected result is achieved.
4. Some basic documentation describing the use of the tool or model and an example of how to apply it (this example can be the same as the test case used above).
5. Code must pass the basic code-quality tests required by IDAES (black and pylint).

Procedures for when Issues are Identified in User Supported Code

In the event that an issue is identified in user-supported code (either due to test failures or an issue being posted) a formal process will be followed in order to inform code owners of the issue and ensure that a sufficient period is allowed for corrections to be made. In the case of test failures, a minimum of one full release cycle (3 months) will be allowed for corrections to be made before the failing code will be removed, during which time a deprecation warning will be attached to the code warning all users of the issues and upcoming removal unless a fix is implemented.

The formal process for addressing a test failure in user-supported code is as follows:

1. A deprecation warning will be immediately attached to the code which will inform users that the code has a test failure and is at risk of being removed if this is not addressed. The warning will list the date the issue was identified and the deadline for when the code will be removed if it is not fixed. The deadline for removal will be two releases in the future, in order to allow for one full release cycle where this warning is seen by users.
2. All failing tests will be xfailed until the issue is resolved.
3. The core developer team will contact the code owner(s) notifying them of the issue and requesting a response.

• If a fix for the issue is proposed, then that fix should remove the deprecation warning and un-xfail the appropriate tests.
• If a fix is not proposed by the deadline, then all the code related to the failing tool/model will be removed from the core repository and moved to a (yet to be determined) archive location.