diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 35fafea9..0c8bb7c3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,8 @@ This document outlines the requirements for contributing a devfile stack or samp The [devfile registry structure](https://github.com/devfile/api/blob/main/docs/proposals/registry/registry-structure.md#repository-structure) design doc provides some useful background information on the structure of resources in a devfile registry (and its Git repository). +When onboarding a new stack or sample, the `Stack Provider` should read and agree to follow their roles and responsibilities outlined in the [Lifecycle](LIFECYCLE.md) doc. + ## Prerequisites The following are required to build the devfile index container image containing your stack or sample: @@ -46,7 +48,7 @@ The following are required to build the devfile index container image containing 6) Add the devfile.yaml and any other necessary files for the stack under the stack folder. 7) Run the `.ci/build.sh` to build the registry into a container image. - + - This will also validate the devfiles in this repository, making sure they conform to a minimum standard. - This step will also be run in the PR build for the repository. diff --git a/LIFECYCLE.md b/LIFECYCLE.md new file mode 100644 index 00000000..51a709be --- /dev/null +++ b/LIFECYCLE.md @@ -0,0 +1,59 @@ +# Lifecycle Maintenance of Devfile Registry Stacks + +The purpose of this document is to clarify the roles and responsibilities for maintaining the devfile stacks and samples present in the [devfile Community registry](https://github.com/devfile/registry). +Devfiles are intended to be used by developers to build their applications with tooling clients that support the devfile spec. As a result, it’s important that stack providers avoid introducing breaking changes or allowing security vulnerabilities to go unremediated which would result in a degradation of our end users applications. In short, we need to ensure our devfiles are trusted enough to be used. In order to achieve this, there is a level of shared responsibility in all of the roles defined below. + + +| Role | Description | +|:------------------------|:----------------------------------------------------------------------------------------------------------------------------------------| +| `Devfile Team` | The team that is responsible for onboarding vendor devfiles for the community registry. | +| `Stack/Sample Provider` | The person or team that is responsible for developing the devfile stack or sample that is available for sharing on our devfile registry. | +| `Tooling Clients` | These are the tools that use devfiles | +| `End Users` | Application developers that consume devfiles for the purpose of building their own custom applications | + +The following sections describe the steps that can happen in the lifecycle of a devfile. + +## [Onboarding](CONTRIBUTING.md) +When a `Stack Provider` is ready to share their devfile to the public registry, they must follow the steps in the [contributing guide](CONTRIBUTING.md) to ensure there’s basic information that identifies the version, owner, description, etc. of the stack or sample. They must also ensure the stack or sample meets minimal testing requirements against the supported clients. + +| Role | Responsibilities | +|:-----------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `Stack Provider` | | +| `Devfile Team` | | + + +## Maintenance +During the course of its lifecycle, a stack or sample may need to be updated by the `Stack Provider`. Types of updates can include: + +* Changing the devfile content itself where components, commands, resources are modified +* Using a more secure container image(s) +* Implementing a new devfile spec version of the existing devfile e.g. multiple versions of devfiles exist for the same runtime supporting different versions of devtools. +* Implementing new additional devfile to the current stack or sample e.g. two devfiles, devfile.yaml and prod.devfile.yaml, exist for the same runtime supporting both inner and outer loop scenarios. +* Implementing a variation of an existing devfile using a different runtime version e.g. Devfile support for both NodeJS v16 and v18 + + +| Role | Responsibilities | +|:-----------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `Stack Provider` | | +| `Devfile Team` | | +| `End User` | | + + +## Deprecation + +When a stack or sample is no longer maintained due to inactivity, lack of timely updates, dependency on end-of-life (EOL) base images, etc it will be marked deprecated. The `Devfile Team` will reach out to the `Stack Provider` and get agreement before proceeding, but if there is no response within a 3-month timeframe, the `Devfile Team` will take action and mark the devfile deprecated. + +* Deprecated devfiles will remain in the community registry for 1 year before it’s removed. + + +| Role | Responsibilities | +|:------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `Devfile Team` | | +| `Stack Provider` | | +| `End User`| | + +### Ownership Transfers + +When a stack provider is no longer able to maintain their stacks, an ownership transfer should take place. The stack provider is responsible to find their replacement. As it is described in the deprecation rules, if a stack is inactive for a long time - because of a failed ownership transfer - it will be marked deprecated. + +In case someone is interested in adopting a stack which is currently deprecated, they should open an issue [here](https://github.com/devfile/api/issues/new/choose). \ No newline at end of file