From 9452493d00e870b60428259e04fb1c896b0c5106 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sergio=20Casta=C3=B1o=20Arteaga?= Date: Tue, 14 May 2024 10:16:12 +0200 Subject: [PATCH] Document landscape data file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Sergio Castaño Arteaga --- README.md | 2 +- crates/cli/src/new/template/data.yml | 50 ++--- crates/cli/src/new/template/guide.yml | 10 +- crates/cli/src/new/template/settings.yml | 251 +---------------------- crates/core/src/data.rs | 2 +- crates/core/src/data/legacy.rs | 3 +- docs/config/data.yml | 247 ++++++++++++++++++++++ 7 files changed, 275 insertions(+), 290 deletions(-) create mode 100644 docs/config/data.yml diff --git a/README.md b/README.md index 553c29c2..b6c4e0cb 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ You can check out how the generated landscapes look like by visiting the [CNCF l **Landscape2** is a CLI tool that generates static websites from the information available in the data sources provided. These data sources are passed to the tool via arguments, usually in the form of *urls* or *local paths*, and are as follows: -- **Landscape data**. The landscape data file is a YAML file that describes the items that will be displayed in the landscape website. For backwards compatibility reasons, this file *must* follow the format and conventions defined in the [CNCF *landscape.yml* file](https://github.com/cncf/landscape/blob/master/landscape.yml). +- **Landscape data**. The landscape data file is a YAML file that describes the items that will be displayed in the landscape website. For more information, please see the [reference documentation](https://github.com/cncf/landscape2/blob/main/docs/config/data.yml). - **Landscape settings**. The settings file is a YAML file that allows customizing some aspects of the generated landscape website, such as the logo, colors, how to group items or which ones should be featured. For more information about the settings file, please see the [reference documentation](https://github.com/cncf/landscape2/blob/main/docs/config/settings.yml). diff --git a/crates/cli/src/new/template/data.yml b/crates/cli/src/new/template/data.yml index abbc5890..fc3ed6ae 100644 --- a/crates/cli/src/new/template/data.yml +++ b/crates/cli/src/new/template/data.yml @@ -1,82 +1,74 @@ -landscape: - - category: - name: Category 1 +# Landscape2 data +# +# This file contains the data that will be used to generate the landscape. +# +# Reference documentation: https://github.com/cncf/landscape2/blob/main/docs/config/data.yml + +categories: + - name: Category 1 subcategories: - - subcategory: - name: Subcategory 1-1 + - name: Subcategory 1-1 items: - - item: + - name: Item 1 crunchbase: https://www.crunchbase.com/organization/cloud-native-computing-foundation description: This is the description of item 1 homepage_url: https://cncf.io logo: cncf.svg - name: Item 1 project: graduated repo_url: https://github.com/cncf/landscape2 twitter: https://twitter.com/CloudNativeFdn - - item: + - name: Item 2 crunchbase: https://www.crunchbase.com/organization/cloud-native-computing-foundation description: This is the description of item 2 homepage_url: https://cncf.io logo: cncf.svg - name: Item 2 project: sandbox repo_url: https://github.com/cncf/landscape2 twitter: https://twitter.com/CloudNativeFdn - - item: + - name: Item 3 description: This is the description of item 3 homepage_url: https://cncf.io logo: cncf.svg - name: Item 3 - - subcategory: - name: Subcategory 1-2 + - name: Subcategory 1-2 items: - - item: + - name: Item 4 crunchbase: https://www.crunchbase.com/organization/cloud-native-computing-foundation description: This is the description of item 4 homepage_url: https://cncf.io logo: cncf.svg - name: Item 4 repo_url: https://github.com/cncf/landscape2 twitter: https://twitter.com/CloudNativeFdn - - item: + - name: Item 5 crunchbase: https://www.crunchbase.com/organization/cloud-native-computing-foundation description: This is the description of item 5 homepage_url: https://cncf.io logo: cncf.svg - name: Item 5 repo_url: https://github.com/cncf/landscape2 - - category: - name: Category 2 + - name: Category 2 subcategories: - - subcategory: - name: Subcategory 2-1 + - name: Subcategory 2-1 items: - - item: + - name: Item 6 crunchbase: https://www.crunchbase.com/organization/cloud-native-computing-foundation description: This is the description of item 6 homepage_url: https://cncf.io logo: cncf.svg - name: Item 6 project: graduated repo_url: https://github.com/cncf/landscape2 twitter: https://twitter.com/CloudNativeFdn - - item: + - name: Item 7 crunchbase: https://www.crunchbase.com/organization/cloud-native-computing-foundation description: This is the description of item 7 homepage_url: https://cncf.io logo: cncf.svg - name: Item 7 project: sandbox repo_url: https://github.com/cncf/landscape2 twitter: https://twitter.com/CloudNativeFdn - - item: + - name: Item 8 description: This is the description of item 8 homepage_url: https://cncf.io logo: cncf.svg - name: Item 8 - - subcategory: - name: Subcategory 2-2 + - name: Subcategory 2-2 items: - item: crunchbase: https://www.crunchbase.com/organization/cloud-native-computing-foundation diff --git a/crates/cli/src/new/template/guide.yml b/crates/cli/src/new/template/guide.yml index a919d381..3d394f03 100644 --- a/crates/cli/src/new/template/guide.yml +++ b/crates/cli/src/new/template/guide.yml @@ -2,15 +2,7 @@ # # This file allows defining the content of the landscape guide. # -# The landscape guide is organized into categories and subcategories. Each of -# these entities requires a name and some content. The content can be provided -# in markdown format. Categories and subcategories names are not required to -# match the ones defined in the landscape data file but, when they do, those -# categories/subcategories will be enriched with some extra information. So -# whenever possible, it's highly recommended that they do. -# -# We recommend using headings of level 4-6 within the content blocks as levels -# 1-3 are reserved to illustrate the hierarchy of categories and subcategories. +# Reference documentation: https://github.com/cncf/landscape2/blob/main/docs/config/guide.yml categories: - category: "Category 1" diff --git a/crates/cli/src/new/template/settings.yml b/crates/cli/src/new/template/settings.yml index ac0c387f..d103522b 100644 --- a/crates/cli/src/new/template/settings.yml +++ b/crates/cli/src/new/template/settings.yml @@ -1,77 +1,13 @@ # Landscape2 settings # # This settings file allows customizing some aspects of the landscape. - -# Foundation (required) -# -# Name of the foundation. This value is used in some labels, so we recommended -# to keep it as short as possible. -# -# foundation: # +# Reference documentation: https://github.com/cncf/landscape2/blob/main/docs/config/settings.yml + foundation: DEMO -# Url (required) -# -# Url where the landscape will be hosted. -# -# url: -# url: http://127.0.0.1:8000 -# Analytics (optional) -# -# Analytics providers configuration. When an analytics provider is set up, some -# additional code from the provider will be injected into the web application. -# -# analytics: -# gtm: # Google Tag Manager configuration -# container_id: # Landscape web application container ID -# - -# Base path (optional) -# -# Base path where the landscape will be hosted. By default the generated -# landscape is prepared to be hosted at the root of the domain. However, if the -# landscape will be hosted in a subpath, this value must be set accordingly. -# -# base_path: / -# - -# Categories (optional) -# -# Categories information is read from the `landscape.yml` data file. The way -# categories are displayed in the web application is computed dynamically based -# on the number of categories and subcategories, as well as the number of items -# on each. Sometimes, however, we may want subcategories to be displayed in a -# specific order within a category (this happens often in the Members category). -# In those cases, it is possible to define that order by overriding a category. -# -# This option can also be used to not display one or more subcategories in the -# landscape. To achieve that, we only need to exclude the subcategory from the -# subcategories list when overriding a category. -# -# categories: -# - name: -# subcategories: -# - -# - -# - -# Colors (optional) -# -# Colors used across the landscape UI. The colors section is optional but, when -# provided, *all colors must be provided*. Colors must be specified using the -# following format: "rgba(, , , )". -# -# colors: -# color1: # Buttons, groups, links -# color2: # Some highlighted items like filters button, search icon -# color3: # Participation stats bars, spinners, modal titles -# color4: # Categories titles in filters, fieldset in filters modal -# color4: # Categories and subcategories frames (odd) -# color5: # Categories and subcategories frames (even) -# colors: color1: "rgba(0, 107, 204, 1)" color2: "rgba(255, 0, 170, 1)" @@ -80,28 +16,6 @@ colors: color5: "rgba(1, 107, 204, 0.7)" color6: "rgba(0, 42, 81, 0.7)" -# Featured items (optional) -# -# This section allows highlighting items that match certain criteria. You can -# define a list of rules and the matching items will be featured in a special -# way in the landscape. -# -# Each rule must define a field for the check as well as the values that will -# trigger a match. At the moment the fields supported are: -# -# - maturity -# - subcategory -# -# When a given item's field matches any of the values provided, it will be -# considered a featured item. For each option, it is possible to also define an -# order (which item would be displayed first) and a label for the item. -# -# featured_items: -# - field: subcategory -# options: -# - value: -# - value: -# featured_items: - field: maturity options: @@ -109,26 +23,6 @@ featured_items: order: 1 label: Graduated -# Footer (optional) -# -# This section allows customizing some aspects of the footer. -# -# footer: -# links: -# facebook: -# flickr: -# github: -# homepage: -# instagram: -# linkedin: -# slack: -# twitch: -# twitter: -# wechat: -# youtube: -# logo: # Foundation logo featured on the footer -# text: # Copyright notice, for example -# footer: links: facebook: "https://www.facebook.com/CloudNativeComputingFoundation/" @@ -144,32 +38,8 @@ footer: youtube: "https://www.youtube.com/c/cloudnativefdn" logo: "https://raw.githubusercontent.com/cncf/artwork/master/other/cncf/horizontal/white/cncf-white.svg" -# Grid items size (optional) -# -# Defines the preferred size of the landscape items in the grid mode. When the -# landscape contains many items, it is recommended to use the `small` size. -# However, if there aren't many items, choosing `medium` or `large` may make -# the landscape look nicer. Users will still be able to adjust the items size -# from the UI using the zoom controls. -# -# grid_items_size: -# grid_items_size: large -# Groups (optional) -# -# In some cases, specially when a landscape contains lots of items, it may be -# interesting to organize them in groups. Each group will be displayed on a -# different tab in the landscape web application. Each entry must contain the -# name of the group (it will be displayed as is) and a list with the categories -# (as defined in the landscape.yml data file) that will be part of this group. -# -# groups: -# - name: -# categories: -# - -# - -# groups: - name: Some categories categories: @@ -179,126 +49,9 @@ groups: categories: - Category 2 -# Header (optional) -# -# This section allows customizing some aspects of the header. -# -# header: -# links: -# github: -# logo: # Foundation logo featured on the header -# header: links: github: "https://github.com/cncf/landscape2" logo: "https://raw.githubusercontent.com/cncf/artwork/master/other/cncf-landscape/horizontal/color/cncf-landscape-horizontal-color.svg" -# Images (optional) -# -# Urls of some images used in the landscape UI. -# -# images: -# favicon: -# open_graph: -# - -# Logos viewbox (optional) -# -# In order to display the logos as large as possible in the landscape, during -# the build process we try to update their viewbox if `adjust` is set to true -# (by default it is when this setting is not provided). However, sometimes this -# does not help and logos may not be displayed correctly. In those cases, it is -# possible to exclude some of them from being adjusted by adding the logo(s) -# file name to the `exclude` list. -# -# logos_viewbox: -# adjust: true -# exclude: -# - logo1.svg -# - logo2.svg -# - -# Name of the members category (optional) -# -# Landscapes usually have a special category dedicated to the members of the -# corresponding foundation. It is possible to use any name for that category, -# but it is important that we define it here as there are some special -# operations that depend on it. -# -# members_category: -# - -# Osano (optional) -# -# Osano cookies consent form configuration. When the Osano configuration is -# provided, some additional code will be injected into the web application. -# -# The `customer_id` and `customer_configuration_id` fields values can be -# obtained from the url in the configuration script code available on the Osano -# site: -# -# https://cmp.osano.com///osano.js -# -# osano: -# customer_id: -# customer_configuration_id: -# - -# Screenshot width (optional) -# -# Width of the landscape screenshots automatically generated (in pixels). -# Screenshots won't be taken if this value is not provided. -# -# screenshot_width: -# screenshot_width: 1500 - -# TAGs (optional) -# -# Projects items can specify which TAG owns them in the `landscape.yml` file -# (by using the `tag` field in the `extra` item's section). However, sometimes -# this information is not available at the item level. This configuration -# section provides a mechanism to automatically asign a TAG to projects items -# based on the categories and subcategories they belong to. -# -# For example, we can define that all projects in the category are -# owned by . When the items are processed, the corresponding TAG will be -# set in the items that match the rule defined. The TAG defined at the item -# level always takes precedence, so when it's present it won't be replaced. -# -# NOTE: TAGs names should only use lowercase case letters and hyphens (no -# spaces or other characters), and should not be prefixed with "tag". The -# subcategories field is optional and, when omitted, all of them will be -# included. -# -# tags: -# : -# - category: -# subcategories: -# - -# - -# : -# - category: -# - -# Upcoming event (optional) -# -# This section allows configuring an upcoming event that will be featured on -# the landscape web application. Expired events won't be displayed. -# -# upcoming_event: -# name: # Event name (required) -# start: # Start date: (required, format: YYYY-MM-DD) -# end: # End date: (required, format: YYYY-MM-DD) -# banner_url: # Event banner image url (required, recommended dimensions: 2400x300) -# details_url: # Event details URL (required) -# - -# View mode (optional) -# -# This section allows customizing the default view mode of the landscape web -# application. The view mode can be set to either `grid` or `card`. When -# omitted, the default view mode is `grid`. -# -# view_mode: -# diff --git a/crates/core/src/data.rs b/crates/core/src/data.rs index 2ff4cfea..1ec30c47 100644 --- a/crates/core/src/data.rs +++ b/crates/core/src/data.rs @@ -1284,10 +1284,10 @@ mod tests { summary_integration: Some("summary_integration".to_string()), summary_integrations: Some("summary_integrations".to_string()), summary_intro_url: Some("summary_intro_url".to_string()), - summary_use_case: Some("summary_use_case".to_string()), summary_personas: Some("summary_personas".to_string()), summary_release_rate: Some("summary_release_rate".to_string()), summary_tags: Some("tag1,tag2".to_string()), + summary_use_case: Some("summary_use_case".to_string()), tag: Some("tag".to_string()), training_certifications: Some("training_certifications".to_string()), training_type: Some("training_type".to_string()), diff --git a/crates/core/src/data/legacy.rs b/crates/core/src/data/legacy.rs index 87ae1c4b..1df24285 100644 --- a/crates/core/src/data/legacy.rs +++ b/crates/core/src/data/legacy.rs @@ -17,6 +17,7 @@ lazy_static! { /// Landscape data (legacy format). #[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)] pub(super) struct LandscapeData { + #[serde(alias = "categories")] pub landscape: Vec, } @@ -173,10 +174,10 @@ pub(super) struct ItemExtra { pub summary_integration: Option, pub summary_integrations: Option, pub summary_intro_url: Option, - pub summary_use_case: Option, pub summary_personas: Option, pub summary_release_rate: Option, pub summary_tags: Option, + pub summary_use_case: Option, pub tag: Option, pub training_certifications: Option, pub training_type: Option, diff --git a/docs/config/data.yml b/docs/config/data.yml new file mode 100644 index 00000000..da865fb3 --- /dev/null +++ b/docs/config/data.yml @@ -0,0 +1,247 @@ +# Landscape2 data +# +# This file contains the data that will be used to generate the landscape. The landscape data is a +# collection of items organized into categories and subcategories. +# +# NOTE: to maintain backwards compatibility with the previous version of the landscape, the data +# file used by v2 is based on the format used by v1. There are some extra fields not available in +# v1, and it's likely that more will be added over time. Most of the fields supported by v1 should +# also be supported by v2, although there might be some exceptions. + +# List of categories in the landscape (required) (this field can also be named `landscape`). +categories: + - # Name of the category (required). + name: My category + + # List of subcategories in this category (required). + subcategories: + - # Name of the subcategory (required). + name: My subcategory + + # List of items in this subcategory (required). + items: + - # Name of the item (required). + name: My item + + # Homepage URL (required). + homepage_url: https://homepage.url + + # File name of the logo (required). The provided logo file is expected to be located in + # the landscape logos path (i.e. `hosted-logos`). URLs are not supported, it must be a + # file name. The logo file must be an SVG file. + logo: logo.svg + + # Description of the item (optional). When the description is not provided, the primary + # repository's description or the organization's description from Crunchbase will be + # used (in that order). This description will be indexed to power the search feature. + description: This is the description of item 1 + + # Alternative `category / subcategory` where this item should be listed in (optional). + # Sometimes we may want to list an item in multiple categories or subcategories. This + # field allows specifying additional locations for an item without having to duplicate + # it. It is possible to provide multiple entries, and the format is as follows: + # + # second_path: + # - "Category 2 / Subcategory 2-1" + # - "Category 3 / Subcategory 3-1" + # + # The alternative category or subcategory name must not contain a slash. + second_path: [] + + # Maturity of the project (optional). This field is only expected on items that + # represent a project that belongs to the foundation. The maturity can be any string, + # but there are some values that have a special meaning: + # + # - "graduated, incubating, sandbox": when used in combination with the date they moved + # to that state (set in `extra` field), a special progress bar will be displayed in + # the item's details view. + # + # - "archived": items in this state will be grayed out. + project: "sandbox" + + # Date at which the member joined the foundation (optional). This field is only + # expected on items that represent a foundation's member. The date should be a string + # using the format 'YYYY-MM-DD'. + joined: "2024-05-14" + + # URL of the primary repository (optional). Some extra information will be collected + # for repositories hosted in GitHub. + repo_url: https://github.com/owner/repo + + # Branch to use when collecting information for the primary repository (optional). + branch: main + + # List of additional repositories (optional). The structure for each repository is as + # follows: + # + # additional_repos: + # - # URL of the repository (required). + # repo_url: https://github.com/owner/repo + # # Branch to use when collecting information for the repository (optional). + # branch: main + additional_repos: [] + + # Crunchbase URL of the organization this item belongs to (optional). + crunchbase: https://www.crunchbase.com/organization/my-organization + + # Twitter URL (optional). + twitter: https://twitter.com/my-organization + + # OpenSSF best practices URL (optional). + url_for_bestpractices: https://www.bestpractices.dev/en/projects/1234 + + # Indicate if the item corresponds to an end user (optional). The value must be a + # boolean. + enduser: false + + # Extra information about the item (optional). + extra: + - # Date at which the project was accepted in the foundation (optional). This field + # is only expected on items that represent a foundation's project. + # Format: 'YYYY-MM-DD'. + accepted: "2024-05-14" + + # Date at which the project was archived (optional). This field is only expected on + # items that represent a foundation's project. Format: 'YYYY-MM-DD'. + archived: "2020-05-14" + + # List of security audits the projet has undergone (optional). The structure for + # each audit is as follows: + # + # audits: + # - # Date of the audit (required). Format: 'YYYY-MM-DD'. + # date: "2024-05-14" + # # Audit type (required). + # type: fuzzing + # # URL of the audit report (required). + # url: https://audit.report.url + # # Name of the vendor who did the audit (required). + # vendor: Vendor name + audits: [] + + # Date of the last annual review presented by this project (optional). This field + # is only expected on items that represent a foundation's project. + # Format: 'YYYY-MM-DD'. + annual_review_date: "2024-05-14" + + # URL of the last annual review presented by this project (optional). This field is + # only expected on items that represent a foundation's project. + annual_review_url: https://annual.review.url + + # Artwork URL (optional). + artwork_url: https://artwork.url + + # Blog URL (optional). + blog_url: https://blog.url + + # Channel to discuss topics related to this item (optional). + chat_channel: "#channel" + + # The name of a project listed in CLOMonitor that matches this item (optional). + # This reference is used to pull the CLOMonitor report for this item and display it + # in the item's details view. CLOMonitor is only enabled for a small number of + # foundations, so this field won't be used in most cases.  + clomonitor_name: "project-name" + + # Dev stats URL (optional). + dev_stats_url: https://dev.stats.url + + # Discord URL (optional). + discord_url: https://discord.url + + # Docker URL (optional). + docker_url: https://docker.url + + # GitHub discussions URL (optional). + github_discussions_url: https://github.discussions.url + + # Gitter URL (optional). + gitter_url: https://gitter.url + + # Date at which the project moved to graduated (optional). Format: 'YYYY-MM-DD'. + # This field is only expected on items that represent a foundation's project, and + # should only be used when adhering to the graduated/incubating/sandbox maturities. + graduated: "2024-05-14" + + # Date at which the project moved to incubating (optional). Format: 'YYYY-MM-DD'. + # This field is only expected on items that represent a foundation's project, and + # should only be used when adhering to the graduated/incubating/sandbox maturities. + incubating: "2024-05-14" + + # LinkedIn URL (optional). + linkedin_url: "https://linkedin.url" + + # Mailing list URL (optional). + mailing_list_url: "https://mailing.list.url" + + # List of links to feature in the item's details view (optional). The structure for + # each link is as follows: + # + # other_links: + # - # Name of the link (required). + # name: Link name + # # URL of the link (required). + # url: https://link.url + other_links: [] + + # Package manager URL (optional). Link to the package manager where the item is + # available. + package_manager_url: https://package.manager.url/my-item + + # Name of the parent project (optional). The parent of a project will be + # highlighted in the item's details view. The parent project must be listed in the + # landscape and the name must match exactly. + parent_project: "Project name" + + # Slack URL (optional). + slack_url: https://slack.url + + # Indicate whether this item is a specification (optional). The value must be a + # boolean. + specification: false + + # Stack Overflow URL (optional). + stack_overflow_url: https://stackoverflow.url + + # Description of the business use case (optional). + # More info: https://github.com/cncf/landscape/blob/master/docs/item_summary.md + summary_business_use_case: "Reduce operational risks associated with software supply chain" + + # Comma separated list of other projects this item integrates with (optional). + # More info: https://github.com/cncf/landscape/blob/master/docs/item_summary.md + summary_integration: "Project 1, Project 2" + + # Alternative field for `summary_integration` (optional). + # More info: https://github.com/cncf/landscape/blob/master/docs/item_summary.md + summary_integrations: "Project 1, Project 2" + + # Video URL of the item's pitch (optional). + # More info: https://github.com/cncf/landscape/blob/master/docs/item_summary.md + summary_intro_url: https://summary.intro.url + + # List of target users this item is intended for (optional). Entries must be + # separated by commas + # More info: https://github.com/cncf/landscape/blob/master/docs/item_summary.md + summary_personas: "Cloud Architects, Platform Engineers" + + # Describes how often a new version of the item is released (optional). + # More info: https://github.com/cncf/landscape/blob/master/docs/item_summary.md + summary_release_rate: "Every 3 months" + + # Keywords that describe the item (optional). The keywords must be separated by + # commas. These keywords will be indexed to power the search feature. + # More info: https://github.com/cncf/landscape/blob/master/docs/item_summary.md + summary_tags: "security, networking, cloud" + + # Description of the technical problem this item solves (optional). + # More info: https://github.com/cncf/landscape/blob/master/docs/item_summary.md + summary_use_case: "Provides security for the software supply chain" + + # Technical Advisory Group (TAG) this item belongs to (optional). When the + # automatic TAG mapping feature is enabled in the landscape settings, the TAG name + # used here must match exactly one of the TAGs listed in the landscape settings + # (provided it refers to the same TAG). + tag: security + + # YouTube URL (optional). + youtube_url: https://youtube.url