(Q3 2019 portion which represents rollout of this feature across platform-core modules, most of the functionality has been implemented in Q2)

Problem statement

The goal is to build the "preview capability" and integrate it with the PR process by providing a link to an environment as a PR notification from the CI. The link should be used by the PO to verify and accept or reject the feature.

Description

This capability aims to enable POs and manual testers to review development work before that work is merged to the mainline branch (usually "master") of any given FOLIO module repository (with the focus on ui- module repositories). The review would be performed on a FOLIO environment deployed at the point in time when the PR is created – hence it will be isolated from other changes that happen across FOLIO module repositories (changes by other teams or unrelated changes by other developers within the same team). If the review is unsuccessful, the PR is closed and additional development work is performed on the feature branch. Once additional work is completed the PR is re-opened. If the review is successful, code review is performed by the developers responsible for maintenance of the particular FOLIO module repository and the code is merged to the mainline branch. At this point the PR is closed and the preview environment is destroyed.

In order to assemble a FOLIO system that will serve as the basis for the preview environment, the CI process running during the PR must provide a "baseline" platform (stripes container and a set of backend module dependencies) for the particular module for which the PR was issued. In order to do so, the CI system will rely on released FOLIO modules and artefacts (see and for the relevant work that has been completed in Q1 2019 with relation to FOLIO release environments).

There are, however, use cases when the developer of the feature may want to rely on unreleased (aka snapshot) dependencies – e.g when a particular feature spans multiple modules and assembling and testing the entire feature would require performing partial module releases that's not been tested for the particular feature. This should be supported but should be tightly controlled by the developer. Any such snapshot dependencies will be refused by the (existing) CI quality gate during the module release process. In order to perform a release the developer needs to convert any such snapshot dependencies into release dependencies.

Please see the attached diagram

for a graphical representation of the above process and how it fits with the existing FOLIO development and release processes.

Consequently, with "PR environments" operational for all ui- modules in FOLIO, the non-isolated and shared "folio-snapshot" environment will no longer play the role of supporting PO and manual tester reviews for new features. In terms of more general (e.g end of quarter) functionality review and testing, those will be moved over to the "folio-release" environment (see ) which offer a much more stable and predictable user experience. The role of folio-snapshot (and folio-testing, provided in a form of Vagrant boxes) in terms of supporting developer work within their individual development environments must be discussed further and is not in scope for this particular epic. It is preferable that the developers experience on their own development machine is closely aligned with the CI processes.

Implementation notes

The implementation can be performed in two stages:

1. Provide the ability to construct the PR environment based on released platform artefacts only – this limits the scope of the task and avoids building additional mechanics in the CI to to construct "mixed" (releases plus snapshots) environments. It does not support directly the use case of building features that span multiple modules but still allows it by developers performing early releases in modules (usually backend) that include partial dependencies for a given feature. This is effectively the scope for the PoC ().

2. Add the ability to include snapshot dependencies in the PR environments – e.g by clearly expressing snapshot dependencies in a configuration file provided along with the PR code (e.g "install-extra.json"). This additional configuration would be picked by the CI build process and allow providing snapshot dependencies in the select cases. The configuration file could be merged to the mainline (with any conflicts needing to resolved at the point of the merge) but it would have to be removed during the release process (CI disallows any snapshot dependencies for released artefacts)

The actual implementation of the CI process may require new approaches in how the FOLIO reference environments are orchestrated – due to potentially large number of feature branches and PR across FOLIO modules at any given point – the existing approach to deployment used when constructing existing reference environments may not be sufficient. See for details. For the "proof of concept" (first stage) – which may be limited to a selected ui- module repository – the existing CI deployment approach (performed by Ansible) is likely sufficient.