From 85757fed82667ad25392991f1b99d6ff8c92c19a Mon Sep 17 00:00:00 2001
From: Eddie Knight <knight@linux.com>
Date: Sun, 29 Dec 2024 10:19:36 -0600
Subject: [PATCH] fix: Improved clarity around required values (#98)
* fix: Improved clarity around required values
Signed-off-by: Eddie Knight <knight@linux.com>
---
schema.cue | 30 +++++++--------
specification-details/aliases.md | 2 +-
specification-details/project.md | 60 ++++++++++++++++++++---------
specification-details/repository.md | 21 +++++++++-
template-minimum.yml | 7 +---
5 files changed, 79 insertions(+), 41 deletions(-)
diff --git a/schema.cue b/schema.cue
index 5032289..8a05f73 100644
--- a/schema.cue
+++ b/schema.cue
@@ -52,10 +52,10 @@ header: {
}
project?: {
- name: string
- homepage: #URL
- funding: #URL
- roadmap: #URL
+ name: string
+ homepage?: #URL
+ roadmap?: #URL
+ funding?: #URL
administrators: [...#Contact]
@@ -66,8 +66,8 @@ project?: {
}]
"vulnerability-reporting": {
- "reports-accepted": bool
- "bug-bounty-available": bool
+ "reports-accepted": bool
+ "bug-bounty-available": bool
"bug-bounty-program"?: #URL
contact?: #Contact
comment?: string
@@ -79,22 +79,22 @@ project?: {
}
documentation?: {
- "detailed-guide"?: #URL
- "code-of-conduct"?: #URL
+ "detailed-guide"?: #URL
+ "code-of-conduct"?: #URL
"quickstart-guide"?: #URL
- "release-process"?: #URL
+ "release-process"?: #URL
"signature-verification"?: #URL
}
}
repository?: {
status: "active" | "abandoned" | "concept" | "inactive" | "moved" | "suspended" | "unsupported" | "WIP"
-
- "accepts-change-request": bool
- "accepts-automated-change-request": bool
- "bug-fixes-only": bool
- "no-third-party-packages": bool
- url: #URL
+
+ url: #URL
+ "accepts-change-request": bool
+ "accepts-automated-change-request": bool
+ "bug-fixes-only"?: bool
+ "no-third-party-packages"?: bool
"core-team": [...#Contact]
diff --git a/specification-details/aliases.md b/specification-details/aliases.md
index 4931875..c3e9129 100644
--- a/specification-details/aliases.md
+++ b/specification-details/aliases.md
@@ -1,6 +1,6 @@
# Aliases
-The following aliases are used throughout the schema.
+The following aliases are used throughout the schema for consistency.
## `assessment`
diff --git a/specification-details/project.md b/specification-details/project.md
index ce0cd7e..2770801 100644
--- a/specification-details/project.md
+++ b/specification-details/project.md
@@ -2,33 +2,30 @@
The `project` object describes the overall project, including basic info, documentation links, repositories, vulnerability reporting, and security details.
----
-
-## `project.name`
-
-- **Type**: `string`
-- **Description**: The name of the project.
-
----
+This field is not required if `header.project-si-source` is supplied.
-## `project.homepage`
+## Required vs Optional Fields
-- **Type**: [URL]
-- **Description**: A path to the project’s landing page. This may be a project website, a version control system repository, or a project/organization page in the VCS.
+Required if `project` is present:
----
+- `name`
+- `administrators`
+- `repositories`
+- `vulnerability-reporting`
-## `project.funding`
+Optional:
-- **Type**: [URL]
-- **Description**: A URL to information about sponsorships, donations, or other funding topics.
+- `homepage`
+- `funding`
+- `roadmap`
+- `documentation`
---
-## `project.roadmap`
+## `project.name`
-- **Type**: [URL]
-- **Description**: A URL pointing to a roadmap or schedule for planned features and releases.
+- **Type**: `string`
+- **Description**: The name of the project.
---
@@ -134,3 +131,30 @@ An object containing references to key documentation URLs.
- **Type**: [URL]
- **Description**: URL to documentation explaining how to verify digital signatures on assets.
+
+---
+
+## `project.homepage` (optional)
+
+- **Type**: [URL]
+- **Description**: A path to the project’s landing page. This may be a project website, a version control system repository, or a project/organization page in the VCS.
+
+---
+
+## `project.funding` (optional)
+
+- **Type**: [URL]
+- **Description**: A URL to information about sponsorships, donations, or other funding topics.
+
+---
+
+## `project.roadmap` (optional)
+
+- **Type**: [URL]
+- **Description**: A URL pointing to a roadmap or schedule for planned features and releases.
+
+---
+
+[URL]: ./aliases.md#url
+[Contact]: ./aliases.md#contact
+[contacts]: ./aliases.md#contact
diff --git a/specification-details/repository.md b/specification-details/repository.md
index b0358d2..15d9da3 100644
--- a/specification-details/repository.md
+++ b/specification-details/repository.md
@@ -2,7 +2,26 @@
The `repository` object specifies repository-related configurations, including status, policies, team members, documentation, license, releases, and security posture.
-This section is not required if the file is intended for use as a parent security insights file with project information to be inherited by multiple repositories.
+This section is not required if the file is intended for use as a parent security insights file with project information to be inherited by multiple repositories via their respective `header.project-si-source`.
+
+## Required vs Optional Fields
+
+Required if `repository` is present:
+
+- `status`
+- `url`
+- `accepts-change-request`
+- `accepts-automated-change-request`
+- `core-team`
+- `license`
+- `security`
+
+Optional top-level fields:
+
+- `documentation`
+- `release`
+- `bug-fixes-only` (assume false if not present)
+- `no-third-party-packages` (assume false if not present)
---
diff --git a/template-minimum.yml b/template-minimum.yml
index 33d3ba4..bb839ac 100644
--- a/template-minimum.yml
+++ b/template-minimum.yml
@@ -10,9 +10,6 @@ header:
project:
name: FooBar
- homepage: https://foo.bar
- funding: https://foo.bar/FUNDING.yml
- roadmap: https://foo.bar/roadmap.html
administrators:
- name: Joe Dohn
affiliation: Foo
@@ -29,12 +26,10 @@ project:
bug-bounty-available: true
repository:
- url: https://github.com/kubernetes/kubernetes
+ url: https://my.vcs/foobar/foo
status: active
- bug-fixes-only: false
accepts-change-request: true
accepts-automated-change-request: true
- no-third-party-packages: false
core-team:
- name: Alice White
affiliation: Foo Bar