openchain-project/reference-material

This repository contains the reference material related to the OpenChain Project

Reference-Material

This repository contains the reference material related to the OpenChain Project. There are around 1,000 documents in this reference library at the moment. These documents are in various formats.

The OpenChain Education Work Group is working on making it easier to access, convert and share key reference material.

We plan to do this through providing the source material in MarkDown. People can change it into PDF documents, Word documents and other formats from there.

The reason for this change is to allow people to easily contribute to our editing via our Reference Library. This is hosted on GitHub and it favors formats like MarkDown that are basically text.

Our first step is to convert some existing documents into MarkDown. This will allow us to begin editing and updating them.

There is an online tool to convert Word documents to MarkDown, which is the first step of the process. You will find it here: https://word2md.com

Our Reference Library is here: https://github.com/OpenChain-Project/Reference-Material

It contains a lot of documents. If you are looking for suggestions on documents to convert first, please see: https://github.com/OpenChain-Project/Reference-Material/blob/master/markdown-conversion-queue.md

If you convert one of these documents to MarkDown, please open a Pull Request to submit the updated document. If you need help with that, please ask our education work group at this mailing list: https://lists.openchainproject.org/g/education/messages

Now you can help with updating the documentation! The process is the same. Update the MarkDown and submit a pull request.

There is a small learning curve to take part in this new drive. However, it is quick, easy and free to get a graphical editor for MarkDown. Download it here: https://panwriter.com. Of course, this is only one of the tools that you can use, as MarkDown is supported by many editors.

Then download background tools for MarkDown: https://pandoc.org/installing.html

You might want to try using git directly at home, so that you can clone the repo, commit changes to it, branch the repo to include your modification in a separate branch, push the branch with your changes and any subsequent commits you add. While it is largely unnecessary, by getting familiar with the tool you could later exploit all the power of it.

That’s it! You are ready to help. We look forward to working together to make sure even more people can take advantage of our reference library as they work towards a more trusted, more efficient and more effective supply chain.

reference-material's Issues

Convert conformance checklist to Markdown

Here is a conformance checklist: https://github.com/OpenChain-Project/Reference-Material/blob/master/Checklists/Official/Conformance-Checklist/2.0/en/Conformance-Compliance-Checklist.docx

Revise the ISO/IEC self-certification questionnaire

We need to review and make the language simpler to prepare for forking for the Security Assurance Spec as well:
https://github.com/OpenChain-Project/Reference-Material/blob/master/Self-Certification-Questionnaire/Official/2.1/en/OpenChain%20Self-Certification%20Questionnaire%202021-11-26.md

[Improvement] Remove duplicated material from Playbooks?

Describe the improvement

The Small and Medium Company Playbooks contain copies of the self-certification questionnaire. This represents a maintenance burden. I suggest that the copies be removed, and replaced with a reference to the questionnaire instead.

Additional context

As the Security spec gains more ground, we will want questionnaires for both specs. That already gives us two documents to maintain and to keep approximately in sync. If we include the license-compliance questionnaire in a Playbook, why would we not include the security questionnaire too? And then the whole thing spirals out of control and civilisation collapses, etc.

Expected behavior

Remove the questionnaire and add a link to it/them in the reference section.

[Improvement] Model Provisions 0.x transition to "finished"

This is an open issue for:
https://github.com/OpenChain-Project/Reference-Material/blob/master/Adoption-Preparation/Model-Provisions/openchain-standards-model-provisions.0.5.md

Perhaps we should include a notice along these lines at the start of the document when we stop the primary drafting and move into long-term mode:

"This document is a living document. It is intended to act as a reference with examples. The material inside the document will be updated on a rolling basis by our community."

[Improvement] Adding additional risks to supply-chain-education-leaflet-version-2-2024

supply-chain-education-leaflet-version-2-2024

Section: Risks caused by failure to comply

What about other risks which should be considered:

1. Export restrictions: Some licenses may restrice exporting, failure to comply may have serious implications (fines, imprisonment)
2. Security vulnerabilities
3. Licenses change: Licenses may change from version to version and may introdice a different set of obligations. Therefore licensing needs to be continuously monitored.

Expected behavior

Other risks besides compliance should be mentioned.

Question: Is there official standard documents template for below mentioned main cases to share sbom to one legal entiry to another?

Hi Shane & others

Generally there is a two documents required to share sbom contained OSS IP details for 2 overall cases.
Case 1: Docx or pdf OSS report to be shared along with our direct product or services
Case 2: Excel or other format to share oss details among Tier n's (Tier 1, Tier 2 ... etc & OEM) so that OEM can collate & use document from Case 1.

I searched here not sure where to get them.. (Tracing a doc is little tough)

Can you please help me?

Thanks

[Improvement] Supplier Leaflet: Steve - This seems very long, overall. I think there's scope for something much shorter and punchier.

This seems very long, overall. I think there's scope for something much shorter and punchier.

[Improvement] Supplier Leaflet: Steve - Potential Improvement under "Typical Open Source Licenses"

Under "Typical Open Source Licenses": “Whether such software should be treated as open source (or handled some other way) should be determined by agreement between the software supplier and the recipient.” Wait, what? This seems to suggest that, if the license is not on the OSI list, supplier and recipient can agree to ignore the license, and I know that’s not what was meant here….

Link of "​Generic FOSS Policy" in the Supplier Education Pack is "404 not found"

The link of "​Generic FOSS Policy" - https://www.linux.com/publications/generic-foss-policy in the OpenChain curriculum file is 404 not found.

$ curl -I --fail https://www.linux.com/publications/generic-foss-policy
curl: (22) The requested URL returned error: 404 

[Improvement] Supplier Leaflet: Steve - When we're discussion the info that needs to be provided, should we just refer to NTIA minimum requirements?

When we're discussion the info that needs to be provided, should we just refer to NTIA minimum requirements?

[New Material] Conversion of General-Compliance-Support-Material / Flowcharts to MarkDown

Suggested new material

{Outline new material}

I would like to submit my work in conversion of the compliance support flowcharts into Markdown (mermaid) format. Hopefully this can be used to provide a more streamline web experience of the material rather than disjointed file based experience. I believe the next steps will be to provide written context linking and summarizing material.

Additional comments

Distribution-Type

flowchart TD
    A[What Type of Distribution?]
    A --> B[In a Device?] --> E(Flowchart 2)
    A --> C[Firmware Update?] --> F(Flowchart 3)
    A --> D[Over the Air?] --> G(Flowchart 4)
    click E "#product" "Flowchart 2"
    click F "#firmware" "Flowchart 3"
    click G "#linking" "Flowchart 4"

Firmware

flowchart TD
    A[Firmware co-located with source code?]
    A --> |yes| B[Is the Code Complete?] 
    A --> |no| C[Written Offer Supplied?]
    C --> |Yes| D[License Text Supplied?]
    C --> |No| F[Provide Written Offer]
    D --> |No| E[Provide License Text]
    B --> |No| H[Fix] --> B
    B --> I[Done!]
    D --> |Yes| B
    B --> E
    F --> D

Linking

flowchart TD
    A[Linking Type?]
    A --> |DYNAMIC| B[LGPL Source code available?] 
    A --> |STATIC| C[Object files of non-LGPL files, scripts to relink and source of LGPL code available?]
    B --> |No| D[Provide LGPL source code]
    C --> |No| E[Provide object files of non-LGPL files, scripts to relink and source of LGPL code]
    B --> |Yes| F[Done!]
    C --> |Yes| F

Product

flowchart TD
    A[Code Delivered with Product?]
    A --> |YES| B[Is the Code Complete?] 
    A --> |NO| C[Written Offer Supplied?]
    B --> |NO| D[Fix] --> B
    C --> |YES| E[License Text Supplied?]
    C --> |NO| F[Provide Written Offer] --> E
    E --> |NO| G[Provide License Text] --> B
    B --> H[Done!]

Using Code

flowchart TD
    A[Will Free Software end up in the final product?]
    A --> |NO| B[Will code generated by the Free Software end up in the final product?]
    A --> |YES| C[Will the product be distributed outside of the organisation?]
    B --> |YES| C
    C --> |YES| D[Is the Free Software on the 'Approved Software' list?]
    C --> |NO| E[Label for 'Internal use only']
    D --> |YES| F[This Free Software may be used for this product]
    B --> |NO| F
    D --> |NO| G[Is the Free Software on the 'Rejected Software' list?]
    G --> |YES| H[This Free Software may not be used for this product]
    G --> |NO| I[Please contact the legal department to obtain approval]

Written Offer

flowchart TD
    A[Written Offer Provided?]
    A --> |YES| B[License Text Supplied?]
    A --> |NO| C[Provide Written Offer] --> B
    B --> |YES| D[Is the Code Complete?]
    B --> |NO| E[Provide License Text] --> D
    D --> |NO| F[Fix] --> D
    D --> |YES| G[Done!]

Convert M&A guide to markdown

Action item coming out of our recent markdown planning call. This document needs to covert to MD to help rebase the content for easy updates.

File is here:
https://github.com/OpenChain-Project/Reference-Material/blob/master/Guides/Official/OpenChain-in-Mergers-and-Acquisitions/2.0/en/Assessment-Of-OS-Practices-In-Merger-and-Acquisition.docx

@kappapiana is taking lead.

todo

• transforming into md
• #32

Convert OpenChain guide for Managers into Markdown

Here is a document to help managers understand OpenChain: https://github.com/OpenChain-Project/Reference-Material/blob/master/Guides/Official/OpenChain-For-Managers/2.0/en/OpenChain%20For%20Managers%20-%20Version%201.0.docx

[Bug] Markdown errors in Self-Certification/Questionnaire

Describe the bug

The Self-Certification/Questionnaire has markdown errors in the external links. The links appear to work but the text is showing markdown syntax instead of human-friendly words.

Screenshots

Error as rendered by the markdown interpreter:

Source code of one of the errors:

Links broken with recent re-organization

Links like https://www.openchainproject.org/news/2017/09/13/fsfe-contributes-reuse-guide-to-openchain-curriculum hold URLs, like; https://github.com/OpenChain-Project/curriculum/blob/master/guides/Reuse-for-OpenChain.md which now no longer work due to recent repo reorganization.

[Improvement] Adding Security and/or Risk staff to supply-chain-education-leaflet-version-2-2024

Add Security and/or Risk stuff to "Let’s learn the basics of open source" section

Security personnel need to know the specificities of OSS security, e.g. known vulnerabilities, CVSS, is the vulnerability exploitable in the current setup, etc.
Risk personnel on the other hand need to know for example how deprecated or unsupported components increase the risks and what kind of mitigation strategies there are. Another risk factor could be a small number of contributors, the OSS project not having good security practices, etc.

Security and/or Risk personnel roles to be added to Different roles in a company have different responsibilities for open source compliance section too.

Add CONTRIBUTING.md file

Create a file that provides advice on how to submit contributions to the repo, as per best practice, e.g. https://patterns.innersourcecommons.org/p/base-documentation

Formal statement format for project with no OSS BOM

Hi all,

Is there a formal statement to give to customers for the projects which has no OSS components.?

we cannot give confirmation that no OSS is being used because we cannot ensure 100% accuracy since there is always limitations to the tools. So we need come up with a statement which sets the tools limitations in place & also state that no OSS evidence has been found after performing the so & so scan.

I wanted to know does there are any statements already in place in Open chain. I searched here https://github.com/OpenChain-Project/Reference-Material
but I did not find anything related to it.

Thanks

Convert merger-and-acquisition-using-OpenChain guide to Markdown

Here is a document about using OpenChain in Mergers and Acquisitions: https://github.com/OpenChain-Project/Reference-Material/blob/master/Guides/Official/OpenChain-in-Mergers-and-Acquisitions/2.0/en/Assessment-Of-OS-Practices-In-Merger-and-Acquisition.docx

Inconsistent use of "artefact" and "artifact"

I've just noticed that I occasionally use the term "artefact" and not "artifact" (see section 1.5 in the model provisions, for example). This is the preferred spelling in British English, but I note that OpenChain 2.1 itself uses "Artifact" in line with US usage, and we should be consistent and adopt "Artifact" throughout.

"Programming Language agnostic"

In my experience, having a tool be programming language agnostic is not common. It is a lot of work to support the myriad programming languages available. Many of the tools now are dual use and they look for security issues as well as license and copyright and there is a large installed base of such tools that have to work together. All of these factors seem to point to a more heterogeneous tooling landscape, especially in larger enterprises.

Some newer tools, like Quartermaster, are focused on compile time instrumentation which holds some promise but of course only for compiled languages.

If the output of the tool, regardless of the programming language, adheres to a specification (e.g. SPDX), then I think the programming language agnostic requirement might be able to be de-emphasized.

WhiteSource is called Mend

Replace WhiteSource with Mend

https://github.com/OpenChain-Project/Reference-Material/blob/master/Adoption-Preparation/Model-Provisions/openchain-standards-model-provisions.0.5.md#q4do-you-use-any-software-tools-or-services-to-assist-with-open-source-license-compliance-for-example-black-duck-scancode-white-source-fossology-sw360

WhiteSource changed their name to Mend already some time ago and I'm suggesting that on this Q4 we'll use Mend instead of WhiteSource

Additional context
Let's use the current name. Of course we could list many other tools too, but it says "For example" so there is no need to list dozens of tools.

How to suggest translation terms?

Hi there,

I just found that Pre-Release version of Traditional Chinese Supplier Education Pack on https://www.openchainproject.org/supplier-education-pack, which is very useful, but some terms at page 2, 40, 48, 54, 77, 80 & 81 of openchain-curriculum-for-2-0-zh-Hant.pptx, seem to be the usage of Simplified Chinese, not Traditional Chinese, "專案" would be more suitable than "項目" here.:

However, it's a Microsoft PowerPoint "pptx" file inside a zip file, doesn't seem to be easy to send a pull request for it with a reviewable diff comparison, how should I suggest or help the translation? Is there any data source that I can send a pull request to?

Many thanks.

Small company playbook links not working

I've noticed the links from the new playbook for small companies are not working, at least in the PDF doc 🙂 Is it possible to get this fixed?

[Improvement] path to conformance: explain levels

Describe the improvement

https://github.com/OpenChain-Project/Reference-Material/blob/master/Path-to-Conformance/Official/en/path-to-conformance-version-1.md talks about 3 levels, but with quick look I did not find definitions what these levels are.

Additional context

Add short description to each level. There are different open source maturity models:

• https://opensource.com/open-organization/resources/open-org-maturity-model has 3 levels
• https://debricked.com/blog/what-is-open-source-maturity-model/ (thanks Calle) has 5 levels

Expected behavior

A reader knows at which level his/her organization is at the moment

[Improvement] Simple workflow

A basic workflow for contributions

I propose to adopt a workflow for changes to the project, based on three levels of branches, to mimic the workflow of software projects. This would help people to contribute in an ordered way.

Branched structure

Invariably the workflow has the top-level branch (master) as a protected branch that only changes any so often, by merging commits from development branches. So basically we would have

a. Main branch

Or master Only touched for major or minor versions changes. The branch is protected, only maintainers can write on it. It does not receive commits directly, but merges from the development branch.

b. Development branch

Is the target branch for pull requests to receive added features or for quick and dirty bug fixes. If it's a quick fix or a small addition, no point making it more complicated. But also no risk to publish for large consumption some half-baked stuff or stuff that would be reverted later.

c. Feature branches

Feature branches are branches that ideally are developed on forks and then pulled in via pull requests.

Some more important sub-projects might be authorized to open a feature branch directly in the main repo and other people could then open pull request to the feature branch instead of the development one.

The workflow

A developer first thing forks the project and works on a new feature branch in the forked repo (can be called feature-something or patch-something or fix-something depending on its nature: substantial addition, small addition or quick fix). Once it's ready, a pull request is made using development as target. If the change is approved, the PR is merged into development, which is the unstable version.

At some point a feature freeze occurs, the content of development is looked at as a whole, see if the additions are ok and consensus is collected and a new version is merged to master, creating a new version, which is labeled accordingly.

Exceptions

Some might be intimidated by this process and just prefer to bring a change through opening an issue. A volunteer should then show how the proposed change could be done and teach through learn-by-doing how to achieve the end result.

Advantages

The master branch will remain a reliable source of information. But people wanting to live on the edge can peek into development to see a more lively, yet possibly inaccurate or prone to change set of documents. We will only have one document instead of multiple documents with different versions. The history is however preserved, through version flags and by inspecting the git history.

Requisites

A developer must have working ability to:

• edit a document in a git environment (either directly on the Github platform, or locally and then push it)
• create a branch and switch to it
• fork a repo
• create a pull request and identify the correct target branch (never master)

Addition of 3.5.2 Consuming

Expansion of the ISO/IEC 5230:2020 Section 3.5 Understanding open source community engagements to include 3.5.2 Consuming.
This amendment proposition aligns to LF Research efforts regarding OSPO activities.

Slide 12 of the TODO Group 2021 OSPO Survey clarifies
"Consuming open source code in products or services"
"Contributing to upstream open source projects"

https://project.linuxfoundation.org/hubfs/LFResearch_TODOGroupOSPOSurvey.pdf

Convert self-certification questionnaire to Markdown

Here is our self-certification questionnaire: https://github.com/OpenChain-Project/Reference-Material/blob/master/Self-Certification-Questionnaire/Official/2.1/en/OpenChain%20Self-Certification%20Questionnaire%202021-11-26.docx

[Improvement] Model Provisions 0.5 - move non-core section to Risk Grid

This is an open issue for:
https://github.com/OpenChain-Project/Reference-Material/blob/master/Adoption-Preparation/Model-Provisions/openchain-standards-model-provisions.0.5.md

The suggestion is to move the "Below is a Series of Optional Model Language Issues in Original Risk Grid Format" section to the Risk Grid (which also needs to be reformatted into a table):
https://github.com/OpenChain-Project/Reference-Material/tree/master/General-Compliance-Support-Material/Risk-Grid

[Improvement] Supplier Leaflet: Steve - Should there be a comment about the Biden White House Executive Order, the CRA, demands from regulated industries, etc?

Should there be a comment about the Biden White House Executive Order, the CRA, demands from regulated industries, etc?

Small Company Playbook PDF formatting not good

Document size is incorrect.
https://github.com/OpenChain-Project/Reference-Material/blob/master/PlayBooks/Official/Version-1/Small-Company/en/OpenChain%20PlayBook%20-%20Small%20Company.pdf

replacing certain PNG into SVG or PDF

[Improvement] Supplier Leaflet: Steve - Not sure whether the reciprocal licenses section should say that it means people can share the modifications, or gain access to the modifications. Or both.

Not sure whether the reciprocal licenses section should say that it means people can share the modifications, or gain access to the modifications. Or both.

the font color of "basic-overview-of-openchain-iso5230_ZH-Hant.pptx" is inconsistent

Hi,

I found that the font color is inconsistent in the slide deck “basic-overview-of-openchain-iso5230_ZH-Hant.pptx”,
such as Page4, Page 7, Page 8, Page 8

Distribution chain

I think the language here is too broad:

Reference-Material/Adoption-Preparation/Model-Provisions/openchain-standards-model-provisions.0.5.md

Line 121 in 175a79e

#### 1.8.2.3.　Delivered to any End User [either as an installer package, a binary, a packaged delivered and installed through an app store, or delivered pre-installed into any device] as anticipated by the Use Case

The Supplier can warrant to accompany the material with a SBOM only when and for the extent they are in the distribution chain. Sometimes the supplier will publish updates directly, but most of the time they only provide their bit to the Customer, and the Customer takes over. So I think there is a need for adding some clarification language like (see the emphasis):

The Supplier warrants that any Open Source components contained within the Software are fully and accurately listed on each Software Bill of Materials made available to the Customer from time to time;
1.8.2.　Are accompanied by all Compliance Artifacts necessary to fully comply with the terms of the Open Source licenses applicable to all components contained within the Software when the Software is
1.8.2.1.　Delivered to the Customer; and*, in case the following acts of delivery are incumbent upon the Supplier*
1.8.2.2.　Delivered to any downstream distributor of the Customer; and
1.8.2.3.　Delivered to any End User [either as an installer package, a binary, a packaged delivered and installed through an app store, or delivered pre-installed into any device] as anticipated by the Use Case

the whole idea of a chain is that you only interact with your downstream, provide all the artifacts and the downstream takes care of it form there on (eg assembling the SBoM with other information gathered from other sources). Exceptionally, the Supplier has contact with further down acts of distribution, but that's more the exception than the rule, in my humble experience. No control, no obligation.