From b3a7ecf7e788b5b280e9b217957bb6537d87ca91 Mon Sep 17 00:00:00 2001 From: John Mertic Date: Mon, 14 Sep 2026 13:06:30 -0400 Subject: [PATCH 1/4] Add standard development guidelines Signed-off-by: John Mertic --- docs/standards.md | 114 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 docs/standards.md diff --git a/docs/standards.md b/docs/standards.md new file mode 100644 index 0000000..08736e1 --- /dev/null +++ b/docs/standards.md @@ -0,0 +1,114 @@ +--- +title: Standards Development + +--- + +# Standards Development in the OpenChain Community + +**Our vision** is a supply chain where open source is delivered with trusted and consistent process management information. **Our mission** is to make that happen. + +The OpenChain Project has an [**extensive global community**](https://www.openchainproject.org/participate) of over 1,000 companies collaborating to make the supply chain quicker, more effective and more efficient. As part of this we make specifications that can turn into standards. + +Making a new specification is a process with a lot of moving pieces. We scope development as outlined below. Prior to the process below kicking in, ideas around new specifications can be shared via our mailing list if they are tagged as proposals, with the recommendation that they are kept in a coherent thread, and ideally also recorded in GitHub. + +We have four guiding principles + +1. Build trust around the open source supply chain. +2. Remember that less is more: + — Define the key requirements of a quality program + — Do this by solving real pain points in the supply chain +3. Keep our specifications limited to what and why (avoid the how and when) + — Embrace different implementations to solve challenges + — Avoid mandating specific process content +4. Be open to all to participate and contribute + +## Standards Development Process + +A Work Group may propose drafting a new specification to the OpenChain Steering Committee in the following manner: + +1. A proposal should be drafted that explains the rationale behind the specification to the Steering Committee [written statement] +2. The proposal should also explain how the activity supports the Project Charter of the OpenChain Project [written statement] +3. Submit to Steering Committee via a formal Steering Committee meeting held adjacent to the next Board Meeting +4. Permission granted and formally ratified, or permission denied, or further questions asked at that meeting +5. If permission is granted, the draft specification can be created. +6. Hold a community kickoff meeting and revisit the OpenChain Project specification development guiding principles. +7. Accept and discuss feedback from anyone who wants to participate either at the [Monthly Community Calls](https://www.openchainproject.org/participate) or on the [specification mailing list](https://lists.openchainproject.org/g/specification) or the relevant GitHub Repository. +8. Record feedback through GitHub issues and their comments for the relevant specification. The current practice is usually to have a GitHub Repository dedicated to each specification under development. We do not accept Pull Requests due to requirements to keep copyright ownership limited and allow easy transfer to international standards organizations. +9. Publish modifications and additions in a draft document contained in relevant GitHub Repository. +10. Open a **Public Comments Period** nine months before our target completion date. This runs for 6 months and only accepts minor updates such as typos or grammar corrections that do not change the requirements of the content. We do not accept any material changes during this period. All other feedback and recommendations are queue for consideration during the next version release cycle. +11. Open a **Freeze Period** three months before our target completion date to allow a 3 month review of any changes made during the Public Comments Period. +12. If a consensus expresses concerns over any changes made during the Public Comments period we would + 1. 1. make changes to accommodate those concerns followed by + 2. an additional 14 day Public Comments period; followed by + 3. another 14 day Freeze period. Anyone with significant reservations on the final draft should state their position/concerns via the spec mailing list. The changes will be accepted once we achieve consensus for the final draft. +13. In the event we do not have consensus on the final version – we would repeat the following cycle until we have consensus: + 1. 1. accommodate changes to address majority concerns; + 2. 14 day Public Comments period; followed by + 3. a 14 day Freeze period cycle. +14. Send the completed draft specification to the OpenChain Steering Committee for formal review and a vote on whether to accept the community recommendations for an updated or new specification. +15. In principle, we target updates to our ISO standards once every five years + +**Please Note:** the final decision on content and release of OpenChain Project specifications lies with the OpenChain Steering Committee. + +### Translating Standards + +We encourage translations of our specifications. However, we want these translations to follow a process to help ensure accuracy. + +#### Policy + +- All translations are based on the English version, which is are official, normative versions of the OpenChain specifications. +- There is one official translation for each language. +- Every translation has one maintainer selected by the OpenChain Project. +- Translations should be reviewed wherever possible by two or more people to ensure integrity, accuracy and completeness. +- Translations are made under the terms of the license of the material being translated. +- Translation version numbers must correspond to the official English version it is based on. + +### **Translation Checklist** + +1. Propose a translation on the monthly calls, [specification mailing list](https://lists.openchainproject.org/g/specification) or other official channel like our WeChat group. + +2. Get a copy of the English version of our specification to facilitate the translation: + [OpenChain ISO/IEC 5230:2020 in MarkDown](https://github.com/OpenChain-Project/License-Compliance-Specification/tree/master/Official/en) + [OpenChain Security Assurance Specification in MarkDown](https://github.com/OpenChain-Project/Security-Assurance-Specification/tree/main/Security-Assurance-Specification) + +3. Add the proposed translations as an Issue to the [License Compliance GitHub Repository](https://github.com/OpenChain-Project/License-Compliance-Specification/pulls) or [Security Assurance GitHub Repository](https://github.com/OpenChain-Project/Security-Assurance-Specification/pulls). + +4. The translation license should be the same as the English original + +5. The translation should also include the following disclaimer: + + > “This is a translation from the original specification in English. In the event there is confusion between this translation and the English version, The English text shall take precedence.” + +6. The translation will be accepted (or flagged for further review) via GitHub. + +7. It will then be announced on the main mailing list and the specification mailing list. + +## Process for Public Comment Periods: + +The OpenChain Study Groups and/or Work Groups may submit material for public comment periods from time to time. This is most frequently done during the **Process for Developing Standards** (see below), but it may be invoked for other purposes. One example is when a guide is being prepared, and wider awareness and commentary is requested from both inside and beyond the OpenChain community. + +The generic process for Public Comment Periods is: + +- A Study Group or Work Group coordinates with the OpenChain General Manager or other relevant staff to discuss whether a public comment period is required +- If necessary, permission is obtained from the OpenChain Governing Board or Steering Committee + - As a general rule, outcomes of the Specification Work Group are subject to approval from the OpenChain Governing Board and/or Steering Committee + - The OpenChain Governing Board generally discusses and approves strategically important matters related to our standards + - The Steering Committee generally discusses and approves new standards or updates to our standards + - Other topics, guides and activities throughout the OpenChain Project may be put to the OpenChain Governing Board or Steering Committee if they are deemed to be strategic to the Project vision and mission, or they will directly impact our standards +- A public comment period is subsequently announced with **a term to be determined by the Study Group or Work Group in question**, or potentially the OpenChain Governing Board or Steering Committee if their approval is involved +- This announcement will contain information on how to contribute to the public comment period for both existing OpenChain Project contributors and the general public +- The Study Group or Work Group announcing the public comment period will then collect feedback for the duration of the comment period. This feedback is generally collected through: + - The Study Group or Work Group mailing list + - The Study Group or Work Group GitHub repository or another OpenChain Project GitHub Repository + - When feedback is obtained through GitHub, it usually takes the form of [GitHub Issues being created](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-an-issue) by commenters +- At the conclusion of the public comment period the issues collected will be addressed by the Study Group or Work Group via their scheduled calls or via their mailing list +- The results of the review of the public comment periods will then be more widely announced via the main OpenChain mailing lists, website or other measures + +## Depreciating Standards + +In principle, all Draft Specifications may find a natural conclusion outside of graduating as an OpenChain Specification, either when it is found unsuitable to address a problem in our domain, or when it is determined that their work is best carried out elsewhere + +1. If such a situation is identified, the relevant chair or GM should explain the rationale [written statement] +2. This would be submitted to the Steering Committee via a formal Steering Committee meeting held adjacent to the next Board Meeting +3. Permission granted and formally ratified, or permission denied, or further questions asked at that meeting +4. If permission is granted, the draft specification would wind down or transfer elsewhere \ No newline at end of file From 6c59da938bfc69f6735b063265bd8c52ec4b365e Mon Sep 17 00:00:00 2001 From: John Mertic Date: Thu, 17 Sep 2026 09:51:25 -0400 Subject: [PATCH 2/4] Rename to `assets.md`, refocus Signed-off-by: John Mertic --- docs/assets.md | 42 +++++++++++++++++ docs/index.md | 5 +- docs/standards.md | 114 ---------------------------------------------- 3 files changed, 45 insertions(+), 116 deletions(-) create mode 100644 docs/assets.md delete mode 100644 docs/standards.md diff --git a/docs/assets.md b/docs/assets.md new file mode 100644 index 0000000..14d106f --- /dev/null +++ b/docs/assets.md @@ -0,0 +1,42 @@ +--- +title: Assets Development +parent: Groups +--- + +# Assets Development for OpenChain Groups + +* TOC +{:toc} + + +OpenChain Groups are natural collaboration points for interested parties to come together to develop various assets for public consumption. These assets generally include: + +- White Papers +- Guides +- Checklists +- Presentations + +The document outlines the general process and guidelines around asset development. + +## Key Requirements for any assets + +- Per the [OpenChain Project Charter IP Poilcy ( Section 12(a) )](https://charter.openchainproject.org), all assets must be licensed under the [Creative Commons Zero License version 1.0 Universal (CC0 1.0)](https://creativecommons.org/publicdomain/zero/1.0/) unless there has been written approval of the OpenChain Governing Board. +- All assets must be developed on openly available tools and platforms. Generally, groups use GitHub ( OpenChain provisions out GitHub repos for all it's groups ), but tools such as Google Docs are acceptable if the contents is available for public consumption and there is a mechanism for public feedback. + +## Soliciting Public Comment/Feedback + +OpenChain Groups developing assets for public consumption will often find it helpful to get broad community feedback on the asset before the asset is formally released. OpenChain Groups are free to set the timeperiod for such feedback, and the below items are best practices for managing public comments/feedback. + +- Announce the asset open for Public Comment/Feedback via the group email list, as well as the general OpenChain mailing list. OpenChain Staff can assist in sharing via OpenChain social channels if interested. +- Ensure there is a clear path to provide feedback. Generally this would be a GitHub Issue, but groups may choose to have feedback sent to the mailing list instead/as well. Do avoid requiring indivduals wanting to provide feedback being required to attend a group meeting, unless there is live discussion around the feedback required. +- Clearly announce the time period for Public Comment/Feedback, and send reminders as the end of the period approaches. +- Ensure all contributors recognize their contributions will be under the project license for the asset ( [Creative Commons Zero License version 1.0 Universal (CC0 1.0)](https://creativecommons.org/publicdomain/zero/1.0/) unless there has been written approval of the OpenChain Governing Board. ) + +## Working with Standards and Standards Bodies + +In some cases, assets from groups may make sense to either make a standards body aware of, or perhaps consider formal standardization. The Linux Foundation through the Joint Development Foundation (JDF) has staff and resources to guide these processes, and should be engaged any time such actions would be considered. Groups can contact for assistance. + +> [!NOTE] +> +> It is critical that if a group is wanting to approach a Standard Body ( such as IEEE or IEC ) that it contacts the JDF *before* making any contact ( which can be contacted through ). JDF has numerous liasion agreements and relationships to guide these engagements. + diff --git a/docs/index.md b/docs/index.md index 9b9477a..2cc0e91 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,8 +9,9 @@ permalink: / Welcome to the central portal for OpenChain Project governance, working group operations, and compliance policies. -{: .note } -> **Linux Foundation Governance:** All OpenChain working groups operate under the antitrust, IP, and code of conduct policies established by [The Linux Foundation](https://www.linuxfoundation.org). +> [!NOTE] +> +> All OpenChain groups operate under the antitrust, IP, and code of conduct policies established in the [OpenChain Project Charter](https://charter.openchainproject.org/). ## How to Contribute to Guidelines diff --git a/docs/standards.md b/docs/standards.md deleted file mode 100644 index 08736e1..0000000 --- a/docs/standards.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Standards Development - ---- - -# Standards Development in the OpenChain Community - -**Our vision** is a supply chain where open source is delivered with trusted and consistent process management information. **Our mission** is to make that happen. - -The OpenChain Project has an [**extensive global community**](https://www.openchainproject.org/participate) of over 1,000 companies collaborating to make the supply chain quicker, more effective and more efficient. As part of this we make specifications that can turn into standards. - -Making a new specification is a process with a lot of moving pieces. We scope development as outlined below. Prior to the process below kicking in, ideas around new specifications can be shared via our mailing list if they are tagged as proposals, with the recommendation that they are kept in a coherent thread, and ideally also recorded in GitHub. - -We have four guiding principles - -1. Build trust around the open source supply chain. -2. Remember that less is more: - — Define the key requirements of a quality program - — Do this by solving real pain points in the supply chain -3. Keep our specifications limited to what and why (avoid the how and when) - — Embrace different implementations to solve challenges - — Avoid mandating specific process content -4. Be open to all to participate and contribute - -## Standards Development Process - -A Work Group may propose drafting a new specification to the OpenChain Steering Committee in the following manner: - -1. A proposal should be drafted that explains the rationale behind the specification to the Steering Committee [written statement] -2. The proposal should also explain how the activity supports the Project Charter of the OpenChain Project [written statement] -3. Submit to Steering Committee via a formal Steering Committee meeting held adjacent to the next Board Meeting -4. Permission granted and formally ratified, or permission denied, or further questions asked at that meeting -5. If permission is granted, the draft specification can be created. -6. Hold a community kickoff meeting and revisit the OpenChain Project specification development guiding principles. -7. Accept and discuss feedback from anyone who wants to participate either at the [Monthly Community Calls](https://www.openchainproject.org/participate) or on the [specification mailing list](https://lists.openchainproject.org/g/specification) or the relevant GitHub Repository. -8. Record feedback through GitHub issues and their comments for the relevant specification. The current practice is usually to have a GitHub Repository dedicated to each specification under development. We do not accept Pull Requests due to requirements to keep copyright ownership limited and allow easy transfer to international standards organizations. -9. Publish modifications and additions in a draft document contained in relevant GitHub Repository. -10. Open a **Public Comments Period** nine months before our target completion date. This runs for 6 months and only accepts minor updates such as typos or grammar corrections that do not change the requirements of the content. We do not accept any material changes during this period. All other feedback and recommendations are queue for consideration during the next version release cycle. -11. Open a **Freeze Period** three months before our target completion date to allow a 3 month review of any changes made during the Public Comments Period. -12. If a consensus expresses concerns over any changes made during the Public Comments period we would - 1. 1. make changes to accommodate those concerns followed by - 2. an additional 14 day Public Comments period; followed by - 3. another 14 day Freeze period. Anyone with significant reservations on the final draft should state their position/concerns via the spec mailing list. The changes will be accepted once we achieve consensus for the final draft. -13. In the event we do not have consensus on the final version – we would repeat the following cycle until we have consensus: - 1. 1. accommodate changes to address majority concerns; - 2. 14 day Public Comments period; followed by - 3. a 14 day Freeze period cycle. -14. Send the completed draft specification to the OpenChain Steering Committee for formal review and a vote on whether to accept the community recommendations for an updated or new specification. -15. In principle, we target updates to our ISO standards once every five years - -**Please Note:** the final decision on content and release of OpenChain Project specifications lies with the OpenChain Steering Committee. - -### Translating Standards - -We encourage translations of our specifications. However, we want these translations to follow a process to help ensure accuracy. - -#### Policy - -- All translations are based on the English version, which is are official, normative versions of the OpenChain specifications. -- There is one official translation for each language. -- Every translation has one maintainer selected by the OpenChain Project. -- Translations should be reviewed wherever possible by two or more people to ensure integrity, accuracy and completeness. -- Translations are made under the terms of the license of the material being translated. -- Translation version numbers must correspond to the official English version it is based on. - -### **Translation Checklist** - -1. Propose a translation on the monthly calls, [specification mailing list](https://lists.openchainproject.org/g/specification) or other official channel like our WeChat group. - -2. Get a copy of the English version of our specification to facilitate the translation: - [OpenChain ISO/IEC 5230:2020 in MarkDown](https://github.com/OpenChain-Project/License-Compliance-Specification/tree/master/Official/en) - [OpenChain Security Assurance Specification in MarkDown](https://github.com/OpenChain-Project/Security-Assurance-Specification/tree/main/Security-Assurance-Specification) - -3. Add the proposed translations as an Issue to the [License Compliance GitHub Repository](https://github.com/OpenChain-Project/License-Compliance-Specification/pulls) or [Security Assurance GitHub Repository](https://github.com/OpenChain-Project/Security-Assurance-Specification/pulls). - -4. The translation license should be the same as the English original - -5. The translation should also include the following disclaimer: - - > “This is a translation from the original specification in English. In the event there is confusion between this translation and the English version, The English text shall take precedence.” - -6. The translation will be accepted (or flagged for further review) via GitHub. - -7. It will then be announced on the main mailing list and the specification mailing list. - -## Process for Public Comment Periods: - -The OpenChain Study Groups and/or Work Groups may submit material for public comment periods from time to time. This is most frequently done during the **Process for Developing Standards** (see below), but it may be invoked for other purposes. One example is when a guide is being prepared, and wider awareness and commentary is requested from both inside and beyond the OpenChain community. - -The generic process for Public Comment Periods is: - -- A Study Group or Work Group coordinates with the OpenChain General Manager or other relevant staff to discuss whether a public comment period is required -- If necessary, permission is obtained from the OpenChain Governing Board or Steering Committee - - As a general rule, outcomes of the Specification Work Group are subject to approval from the OpenChain Governing Board and/or Steering Committee - - The OpenChain Governing Board generally discusses and approves strategically important matters related to our standards - - The Steering Committee generally discusses and approves new standards or updates to our standards - - Other topics, guides and activities throughout the OpenChain Project may be put to the OpenChain Governing Board or Steering Committee if they are deemed to be strategic to the Project vision and mission, or they will directly impact our standards -- A public comment period is subsequently announced with **a term to be determined by the Study Group or Work Group in question**, or potentially the OpenChain Governing Board or Steering Committee if their approval is involved -- This announcement will contain information on how to contribute to the public comment period for both existing OpenChain Project contributors and the general public -- The Study Group or Work Group announcing the public comment period will then collect feedback for the duration of the comment period. This feedback is generally collected through: - - The Study Group or Work Group mailing list - - The Study Group or Work Group GitHub repository or another OpenChain Project GitHub Repository - - When feedback is obtained through GitHub, it usually takes the form of [GitHub Issues being created](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-an-issue) by commenters -- At the conclusion of the public comment period the issues collected will be addressed by the Study Group or Work Group via their scheduled calls or via their mailing list -- The results of the review of the public comment periods will then be more widely announced via the main OpenChain mailing lists, website or other measures - -## Depreciating Standards - -In principle, all Draft Specifications may find a natural conclusion outside of graduating as an OpenChain Specification, either when it is found unsuitable to address a problem in our domain, or when it is determined that their work is best carried out elsewhere - -1. If such a situation is identified, the relevant chair or GM should explain the rationale [written statement] -2. This would be submitted to the Steering Committee via a formal Steering Committee meeting held adjacent to the next Board Meeting -3. Permission granted and formally ratified, or permission denied, or further questions asked at that meeting -4. If permission is granted, the draft specification would wind down or transfer elsewhere \ No newline at end of file From b49d2dd48974f19e0d3902388a52c030e233369e Mon Sep 17 00:00:00 2001 From: John Mertic Date: Thu, 17 Sep 2026 09:57:17 -0400 Subject: [PATCH 3/4] Make native GFM alerts render correctly Signed-off-by: John Mertic --- _config.yml | 4 ++++ _plugins/gfm_callouts.rb | 19 +++++++++++++++++++ 2 files changed, 23 insertions(+) create mode 100644 _plugins/gfm_callouts.rb diff --git a/_config.yml b/_config.yml index 39aeba1..ccbcccd 100644 --- a/_config.yml +++ b/_config.yml @@ -46,6 +46,10 @@ defaults: values: layout: "default" +kramdown: + input: GFM + gfm_quirks: [paragraph_end] + callouts: highlight: color: yellow diff --git a/_plugins/gfm_callouts.rb b/_plugins/gfm_callouts.rb new file mode 100644 index 0000000..cc88b6c --- /dev/null +++ b/_plugins/gfm_callouts.rb @@ -0,0 +1,19 @@ +Jekyll::Hooks.register [:posts, :pages, :documents], :pre_render do |doc| + # Map GFM alert tags to Just the Docs classes + callout_map = { + 'NOTE' => 'note', + 'TIP' => 'highlight', + 'WARNING' => 'warning', + 'IMPORTANT' => 'important', + 'CAUTION' => 'important' + } + + callout_map.each do |gfm_type, jtd_class| + # Convert '> [!NOTE]' followed by content into Just the Docs block attributes + pattern = /^>\s*\[!#{gfm_type}\]\s*\n((?:^>.*$\n?)+)/i + doc.content.gsub!(pattern) do + content = $1 + "#{content}{: .#{jtd_class} }\n" + end + end +end From 2fea09ea5d3e91f082bccd95a6987f01646ffadd Mon Sep 17 00:00:00 2001 From: John Mertic Date: Thu, 17 Sep 2026 09:58:59 -0400 Subject: [PATCH 4/4] Cleanup Signed-off-by: John Mertic --- docs/assets.md | 1 - docs/index.md | 1 - 2 files changed, 2 deletions(-) diff --git a/docs/assets.md b/docs/assets.md index 14d106f..b30da60 100644 --- a/docs/assets.md +++ b/docs/assets.md @@ -37,6 +37,5 @@ OpenChain Groups developing assets for public consumption will often find it hel In some cases, assets from groups may make sense to either make a standards body aware of, or perhaps consider formal standardization. The Linux Foundation through the Joint Development Foundation (JDF) has staff and resources to guide these processes, and should be engaged any time such actions would be considered. Groups can contact for assistance. > [!NOTE] -> > It is critical that if a group is wanting to approach a Standard Body ( such as IEEE or IEC ) that it contacts the JDF *before* making any contact ( which can be contacted through ). JDF has numerous liasion agreements and relationships to guide these engagements. diff --git a/docs/index.md b/docs/index.md index 2cc0e91..e5ab715 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,7 +10,6 @@ permalink: / Welcome to the central portal for OpenChain Project governance, working group operations, and compliance policies. > [!NOTE] -> > All OpenChain groups operate under the antitrust, IP, and code of conduct policies established in the [OpenChain Project Charter](https://charter.openchainproject.org/). ## How to Contribute to Guidelines