IDAES Examples Standards

Introduction

The IDAES examples repository contains Jupyter Notebooks and associated Python code to demonstrate and teach the capabilities of the IDAES core. This page lays out standards for contributing, maintaining, and deprecating example notebooks.

Lifecycle of an example

Like all things, examples have a lifecycle of Creation → Maintenance → End-of-life.

Creation

Examples may be created for an existing feature -- something already merged into the IDAES master branch -- or for a feature being developed. In either case, the procedure for creating the example is to create a PR, add the example, get tests to pass, and get the content reviewed before merging.

In the case where the associated code is in a PR, you can work on the example in parallel by changing the idaes-pse dependency in the pyproject.toml file to point at the URL for your PR. This will need to be changed back to its original value before the example can be merged in. In this case, you should also make sure that the two PRs (the one in idaes-pse and the one in examples) reference each other in the first section of the PR conversations, so it is easy to track this dependency.

Maintenance

Once an example is merged into the main branch, it is expected to continue to pass tests even as the IDAES codebase changes. If an example starts failing tests there are three options:

• If somebody is willing to fix it in the current release cycle, they should open a PR and include it in the release board.
• If somebody is willing to fix it by the next release cycle, they should open a PR that moves the example to a holding area (mechanics specified elsewhere). This is a temporary condition. It will not be included in documentation or tests, but the code will remain in the examples repo for the current release.
• If nobody volunteers to fix it before the freeze date for the next release cycle, it will be moved to an 'archive' area where it is no longer distributed as part of IDAES. This also applies to 'held' examples from the previous release cycle that are not yet working and reviewed.

End-of-life

As described in the Maintenance section above, examples will move to an archive area (different repository) when they are not working and there is no maintainer (or possibly other reasons). They may stay in this area for a long time, but there is no guarantee of preservation. It is expected that periodically the archive will be cleaned up and outdated material removed. Anyone interested in long-term preservation of an example should handle this themselves.

Content standards

This section provides an overview of the expected contents and placement of examples in the examples repository. For details, see README-developer.md in that repository.