Managing Tools/Frameworks/Dependencies Version - v0.1 DRAFT

What is in scope?

• Upgrades to any of the Officially Supported Technologies

Terminology

• FOLIO distribution - All deployable artifacts produced by the FOLIO community and included in a flower release, e.g. jar files, docker images, JS bundles, vagrant boxes
• Infrastructure Components - Components that are required to run, build FOLIO but are not packaged with the FOLIO distribution
• Non Infrastructure Components - Components that are a part of FOLIO distribution
• LTS - Long Term Support

What is out of scope?

• Process for Introducing new components to the platform. ADR/RFC process is in place for such cases.
• Deciding what makes is part of Officially Supported Technologies and what is not
• Resource planning for upgrades

Objectives

• Ensure third-party component usage is consistent across teams
• Ensure that the FOLIO platform consistently uses component versions that are in LTS
• Ensure that fixes to known CVEs are incorporated in a timely manner
• Ensure that the development/operational aspect of making the upgrade is well planned

Assumptions

• TC can delegate any of the work related to upgrades to that security group or a sub-group as it sees fit.
• If the decision to upgrade fits the ADR criteria, document the decision as an ADR
• While it is good to have some time-bound expectations, it is not very clear that it is something that can be enforced practically. That said, this process is expected to work based on an honor system. Teams should try and adopt these guidelines and realize that this will result in the community building a robust platform

Process Overview

Documenting Usage

• Happens Once a year
• Teams/individuals are expected (could be a gating factor during a release) to document their usage of tools/frameworks/dependencies by filling out the following information. Teams can also flag libraries that are going out support for a variety of reasons in the next 6-9 months
• Information collected is expected to be submitted to the TC
• The TC reviews the data for compliance by checking if any of the app/module is using an unsupported version
• If the data reveals a certain module/app is using unsupported versions, the team owning the module/app is expected to address the issue within 6-9 months

Upgrade Scenarios

TC-driven 

• Applies to the situation where the TC recommends an upgrade to keep up with changing versions 
• TC monitors the release of new LTS version as they become available and recommends teams to schedule an upgrade within 6-9 months of the LTS release
• TC works with the team to establish an upgrade plan

Team-driven 

• Applies to the situation where the team is in need of a particular version to take advantage of some new feature, performance enhancements, or a bug fix
• The team will present the proposal to the TC that includes the upgrade plan
• The proposal can be presented to the TC in one of the weekly meetings
• TC will review the proposal and make edits as needed
• The team works with the stakeholders to schedule this upgrade

Security-driven 

• Applies to the scenario where libraries needed to be upgraded to address a major critical security vulnerability
• TC will work with all affected teams to establish a timeline for rolling out the fix to the CVE

Upgrading Infrastructure vs. Non Infrastructure Components

Infrastructure Components 

• Given the constraints the community has on testing the platform on multiple versions of supported infrastructure components, support will be limited to just one version of the infrastructure component, at any given time.
• Service providers can proceed to use unsupported versions at their own risk
• Intent for upgrading an infrastructure component MUST be submitted as a proposal (MUST include justification) to the TC at least one release cycle before the intended upgrade
• TC deliberates the proposal with all relevant stakeholders to arrive at a consensus. The proposal can ONLY move forward when consensus is reached among the stakeholders (e.g.hosting providers, implementors, systems operators, DevOps)
• In the event the proposal to upgrade moves forward, plans should be put in place to execute it in the next release cycle. Teams should consider making this upgrade very early in the release cycle to give teams enough time to execute all available regression test suites

Note :

In the case when discussions related to the upgrade is not resulting in a consensus, steps should be taken to resolve the situation as soon as possible. Everyone should realize that protracted discussions around upgrades will certainly hold back the community in terms of technological advancements to the platform  

Non Infrastructure Components 

• Intent for upgrading an non infrastructure component MUST be submitted as a proposal (MUST include justification) to the TC
• Teams will decide their own timeline for upgrading non infrastructure components.  However, teams SHOULD not vary from the supported technology list for major components.
• Timeline for deprecating usage of older versions should definitely be considered while making plans for the upgrade
• In the event of any upgrade affecting build/infrastructure pipeline, the DevOps (as they might the first to see) team will communicate the impact to the developer community

Upgrade Plan

• Upgrade Instructions
• Breaking Changes/ Known Issues/Incompatibilities
• Components Affected
• Rollback Instructions
• Regression & Performance Test Plans

Questions?

• Who will work on the resource plan when the upgrade initiative is TC driven?
• Do we have reserved capacity to address tech debt items in each release?
• Who are the stakeholders for the upgrade plan and how do we communicate it?
• How tight the constraints needs to be? TC has to be involved more. Is it worth ?