Establishing a Repository for Intents and Defining a Process for Intent Submissions

[anshulsao]

Problem Statement

As the community around the Intent-based Catalog (InCa) grows, there arises a need to have a centralized repository that holds a list of all available intents. This repository will serve as a single source of truth for developers and users to explore, utilize, and contribute to the available intents. Furthermore, a standardized process and a checklist to guide the submission and validation of new intents are crucial to maintain the quality and consistency of the intents in the repository.

Suggested Solution

1. Centralized Intent Repository

A dedicated GitHub repository can serve as the centralized place to hold all the intents. This repository will contain:

• A directory for each intent, which includes its manifest, JSON schema, and any additional documentation or auxiliary files.
• A README.md file that provides an overview of the repository, guidelines for contribution, and a list (or table) of all available intents with brief descriptions and links to their respective directories.

2. Process for Intent Submission

To streamline the addition of new intents, a clear and straightforward process should be established. Here’s a proposed process:

a. Intent Proposal: Users propose a new intent by opening an issue in the GitHub repository, describing the intent, its use cases, and potential schema.

b. Community Discussion: The proposed intent is discussed by the community, exploring its validity, utility, and any potential modifications or improvements.

c. Intent Development: Upon agreement, the user (or another contributor) develops the intent, including creating the manifest and JSON schema, adhering to the established guidelines.

d. Pull Request: The developed intent is submitted to the repository via a pull request (PR), which is then reviewed by the community and/or repository maintainers.

e. Merge & List: Once the PR is approved, it is merged into the repository, and the new intent is added to the list in the README.md file.

3 Structuring Intent Declarations in the Repository

To maintain a structured, comprehensible, and consistent repository, it's pivotal to establish a standardized format and set of requirements for declaring intents. This ensures that each intent is self-descriptive, adheres to the principles of the Intent-based Catalog (InCa), and provides necessary details and examples for users and systems.

Proposed Solution

1. Intent Declaration Structure

Each intent declaration should contain the following files:

• README.md: A markdown file providing comprehensive documentation about the intent.
• intent.json: A JSON file containing meta-information about the intent.
• schema.json: A JSON schema file that defines the expected structure and data types for the intent.
• sample.json: A JSON file providing a sample instance adhering to the defined schema.

2. Checklist for Validating Intents

• Defined Purpose: Does the intent have a clear and specific purpose?
• Documentation: Is the intent adequately documented in the README.md?
• Schema Definition: Is the schema clearly defined in schema.json?
• Sample Instance: Is a valid sample instance provided in sample.json?
• Implementation Neutrality: Is the intent neutral regarding specific technologies or implementations?
• Community Applicability: Does the intent address common or impactful use cases within the community?
• Non-Redundancy: Does the intent avoid duplicating the functionality of existing intents?

3. Sample intent.json

{
  "name": "ExampleIntent",
  "description": "A brief description of what ExampleIntent achieves or represents.",
  "schema": "https://xyz.com/path_to_intent/schema.json",
  "example": "https://xyz.com/path_to_intent/sample.json"
}

name: A string representing the name of the intent.
description: A string providing a concise description of the intent.
schema: A string representing the absolute url to the schema definition.
example: A string representing the absolute url to the example JSON structure.

Conclusion

Establishing a centralized repository for intents and defining a clear process and checklist for intent submission will foster a structured, consistent, and collaborative environment for the InCa community. This approach ensures that the intents are of high quality, relevant, and beneficial to the users and developers within the ecosystem.

[rr0hit]

We should not be using Intent-based Catalog and Infrastructure as Catalog interchangeably right now

[krishankirtifacets]

We should have a process where contributor of an intent can credit the intent contribution on their name.

[krishankirtifacets]

We should have a rejection criteria listed here, right now as a contributor I don't know what can reject my contribution.

[krishankirtifacets]

We can include if some user comes up with a different version of the same intent, will we be accepting the intent contribution.

[4adway]

How would the backward compatibility be maintained whenever there'll be modifications suggested for an existing intent?

[rr0hit]

What qualifies as an Intent Type?

• If an intent is complete enough (detailed enough) to manifest it, it qualifies to be an Intent Type
• If it can be a flavor of an existing intent, is should be remodelled as a flavor
• There can be competing flavors say generic_application, web_application, etc

[pramodh-ayyappan]

We can establish a template repository that includes a framework for generating intent, including elements such as a readme, schema.json, sample.json etc. We have previously employed a similar approach to create a foundational template for tf modules in our product, where we have outlined the basic structure - https://github.com/Facets-cloud/module-template.