From 758d81cd7a8031323d1a5a34f3ce278ebb9eccda Mon Sep 17 00:00:00 2001 From: DBees Date: Thu, 4 Jan 2024 17:57:15 -0800 Subject: [PATCH 1/9] Upload draft of specification process for review --- process/OpenHW-Specification-Process.md | 152 ++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 process/OpenHW-Specification-Process.md diff --git a/process/OpenHW-Specification-Process.md b/process/OpenHW-Specification-Process.md new file mode 100644 index 000000000..4b6a2ce72 --- /dev/null +++ b/process/OpenHW-Specification-Process.md @@ -0,0 +1,152 @@ +# OpenHW Process Document: Specification Process, States and Format + +## Revision History + +This document desbribes OpenHW's specification process and format. +It was adopted by consensus in the TWG meeting of July 2023. + +The V1.0 of this document reflects the agreements made at that meeting and adds additional details. + +| Date | Version | Notes | +| :---------- | :------ | :---------------------------------------------------- | +| 22 Jan 2024 | 1.0 | Formal draft reflecting July 2023 google docs | + +## Specification Process + +### Overview + +OpenHW uses a lightweight specification development process to produce specification documents that are developed and frozen in a designated Task Group, then ratified and released by TWG. + +### Requirements for OpenHW Specification Process + + +#### Basics + +| Number | Issue | Comment | +| :--- | :------ | :-------------------------------------------------------------------------------- | +| 1 | Nature of the specification | A collective derivative work from the individual member contributions, together with staff contributions | +| 2 | Editors of the specification | OpenHW via its members and staff | +| 3 | Contributions by non-members | For further study | +| 4 | Eclipse Specification Process | Not used | + +#### Contributions into the Specification + +| Number | Issue | Comment | +| :--- | :------ | :-------------------------------------------------------------------------------- | +| 1 | License options for contributions: | | +| 1.1 | Apache 2.0 | As per OpenHW Member Agreement | +| 1.2 | Solderpad 2.1 | As per OpenHW Member Agreement | +| 1.3 | Commons Attribution Share Alike 4.0 International license | Agreed by OpenHW CEO April 2023 | +| 2 | Patent Grant included in contribution license: | | +| 2.1 | Apache 2.0 | Yes | +| 2.2 | Solderpad 2.1 | Yes | +| 2.3 | Commons Attribution Share Alike 4.0 International license | No | +| 3 | Essential patents must be disclosed by contributor | No | +| 4 | Contribution Process | EDP/ Committers merging pull requests / Contributors sign ECA or MCCA | + + +#### Publication of the Specification + +| Number | Issue | Comment | +| :--- | :------ | :-------------------------------------------------------------------------------- | +| 1 | Specification published by | OpenHW on Github and/or ReadtheDocs and/or website | +| 2 | Copyright holder on specification | OpenHW on behalf of contributors (member), who hold the copyright jointly. | +| 3 | License used for publication | Same license as used for contributions | +| 4 | Copyright Grant included in specification publication | As per publication license: } +| 5.1 | Apache 2.0 | Yes | +| 5.2 | Solderpad 2.1 | Yes | +| 5.3 | Commons Attribution Share Alike 4.0 International license | Yes | +| 6 | Patent Grant included in specification publication | As per publication license | +| 6.1 | Apache 2.0 | Yes | +| 6.2 | Solderpad 2.1 | Yes | +| 6.3 | Commons Attribution Share Alike 4.0 International license | No | +| 7 | Essential patents disclosed by OpenHW | No | +| 8 | License text included within the specification text | No - referall only | +| 0 | "No-warranty" or disclaimer | Required | + + +### Specification States + +The ratification or completion state ais meant to be written in each OpenHW specification so that a reader will be aware of the state of completion of the Specification +These are the OpenHW Specification States: + +- “OpenHW Specification - In Development" +- "OpenHW Specification - In Review" +- "OpenHW Specification - Released" + +#### "OpenHW Specification - In Development" + +When the specification is initiated, all drafts will be labelled as “OpenHW Specification - In Development" + +Revision numbers should be of the form 0.Y.Z + + +#### "OpenHW Specification - In Review" + +When the specification is frozen for technical review, all drafts will be labelled as "OpenHW Specification - In Review" + +Revision numbers should be of the form 0.Y.Z + +#### "OpenHW Specification - Released" + +When the specification is published, the publication copy will be labelled as "OpenHW Specification - Released" +Revision numbers should be of the form X.Y.Z, starting with 1.0.0 as the initially released version. + +#### "OpenHW Specification Revision" + +Process for labelling and numbering released specifications in revision to be decided. + + +## Specification Format + +The following sections must be included in the OpenHW Specification + +### Title + +The Title should be of the form "OpenHW Specifciation: Title" + +### Revision History + +Prior to release a table of draft revisions should be included, which can included description of content in each draft + +Upon release and subsequently, the Revision History should list only released specification versions, starting with 1.0.0. +The table should include Revision, Date, and Description. The Description should include a high level description of the content. + +### Specification States + +The specification state must be listed, e.g. + +'The state of this specification is "OpenHW Specification - Released"' + + +### License + +The Publication License is listed, together with a URL link to the source of the license. + + +The following is an example of an appropriate license statement: + +" +Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +### No-warranty +The following no-warranty text is included: + +"Unless required by applicable law or agreed to in writing, this Specification and any accompanying software or hardware distributed under the License are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License." + +### Copyright +The following opyright text is included: + +"Copyright © YEAR OF PUBLICATION OpenHW Group. You may use, copy, modify, and distribute this work under the terms of the License, subject to the conditions specified in the License." + +### Footer + +In cases where the specification is rendered in PDF format, a footer should be included on each page, including OpenHW “Specification Title” and "Copyright © YEAR OF PUBLICATION OpenHW Group" + + + + + + From e07e38c7a03a9a460b5413e55236297ee06c8d2d Mon Sep 17 00:00:00 2001 From: DBees Date: Tue, 9 Jan 2024 16:47:34 -0800 Subject: [PATCH 2/9] Updated following review comments --- process/OpenHW-Specification-Process.md | 82 +++++++++++++++---------- 1 file changed, 50 insertions(+), 32 deletions(-) diff --git a/process/OpenHW-Specification-Process.md b/process/OpenHW-Specification-Process.md index 4b6a2ce72..d653e7d89 100644 --- a/process/OpenHW-Specification-Process.md +++ b/process/OpenHW-Specification-Process.md @@ -3,13 +3,13 @@ ## Revision History This document desbribes OpenHW's specification process and format. -It was adopted by consensus in the TWG meeting of July 2023. +The overall approach was adopted by consensus in the TWG meeting of July 2023 based on power point presentations and other documents. The V1.0 of this document reflects the agreements made at that meeting and adds additional details. -| Date | Version | Notes | -| :---------- | :------ | :---------------------------------------------------- | -| 22 Jan 2024 | 1.0 | Formal draft reflecting July 2023 google docs | +| Date | Version | Notes | +| :---------- | :------ | :-------------------------------------------------------- | +| 22 Jan 2024 | 1.0 | Formal draft reflecting July 2023 TWG meeting materials | ## Specification Process @@ -24,7 +24,7 @@ OpenHW uses a lightweight specification development process to produce specifica | Number | Issue | Comment | | :--- | :------ | :-------------------------------------------------------------------------------- | -| 1 | Nature of the specification | A collective derivative work from the individual member contributions, together with staff contributions | +| 1 | Nature of an OpenHW Group specification | A collective derivative work from the individual member contributions, together with staff contributions | | 2 | Editors of the specification | OpenHW via its members and staff | | 3 | Contributions by non-members | For further study | | 4 | Eclipse Specification Process | Not used | @@ -33,16 +33,20 @@ OpenHW uses a lightweight specification development process to produce specifica | Number | Issue | Comment | | :--- | :------ | :-------------------------------------------------------------------------------- | -| 1 | License options for contributions: | | -| 1.1 | Apache 2.0 | As per OpenHW Member Agreement | -| 1.2 | Solderpad 2.1 | As per OpenHW Member Agreement | +| 1 | Licenses accepted for contributions to OpenHW Specs | | +| 1.1 | Apache 2.0 | As per OpenHW Member Agreement, contributions can be made using this license | +| 1.2 | Solderpad 2.1 | As per OpenHW Member Agreement, contributions can be made using this license | | 1.3 | Commons Attribution Share Alike 4.0 International license | Agreed by OpenHW CEO April 2023 | -| 2 | Patent Grant included in contribution license: | | -| 2.1 | Apache 2.0 | Yes | -| 2.2 | Solderpad 2.1 | Yes | -| 2.3 | Commons Attribution Share Alike 4.0 International license | No | -| 3 | Essential patents must be disclosed by contributor | No | -| 4 | Contribution Process | EDP/ Committers merging pull requests / Contributors sign ECA or MCCA | +| 2 | Patent Grant included in contribution license: | | +| 2.1 | Apache 2.0 | Yes, patent grant included in contributions | +| 2.2 | Solderpad 2.1 | Yes, patent grant included in contributions | +| 2.3 | Commons Attribution Share Alike 4.0 International | No patent grant included | +| 3 | Essential patents must be disclosed by contributor | No, Contributors are not required to disclose essential patents | +| 4 | Copyright Grant included in contribution license: | | +| 4.1 | Apache 2.0 | Yes, copyright grant included in contributions | +| 4.2 | Solderpad 2.1 | Yes, copyright grant included in contributions | +| 4.3 | Commons Attribution Share Alike 4.0 International | Yes, copyright grant included in contributions | +| 4 | Contribution Process | Follows EDP/ Committers merging pull requests / Contributors sign ECA or MCCA | #### Publication of the Specification @@ -52,49 +56,63 @@ OpenHW uses a lightweight specification development process to produce specifica | 1 | Specification published by | OpenHW on Github and/or ReadtheDocs and/or website | | 2 | Copyright holder on specification | OpenHW on behalf of contributors (member), who hold the copyright jointly. | | 3 | License used for publication | Same license as used for contributions | -| 4 | Copyright Grant included in specification publication | As per publication license: } -| 5.1 | Apache 2.0 | Yes | -| 5.2 | Solderpad 2.1 | Yes | -| 5.3 | Commons Attribution Share Alike 4.0 International license | Yes | +| 4 | Copyright Grant included in specification publication | As per publication license: | +| 5.1 | Apache 2.0 | Yes, copyright grant included with OpenHW publication | +| 5.2 | Solderpad 2.1 | Yes, copyright grant included with OpenHW publication | +| 5.3 | Commons Attribution Share Alike 4.0 International license | Yes, copyright grant included with OpenHW publication | | 6 | Patent Grant included in specification publication | As per publication license | -| 6.1 | Apache 2.0 | Yes | -| 6.2 | Solderpad 2.1 | Yes | -| 6.3 | Commons Attribution Share Alike 4.0 International license | No | +| 6.1 | Apache 2.0 | No patent grant provided by OpenHW but patents rights granted under contribution | +| 6.2 | Solderpad 2.1 | No patent grant provided by OpenHW but patents rights granted under contribution | +| 6.3 | Commons Attribution Share Alike 4.0 International license | No patent grant included with OpenHW publication | | 7 | Essential patents disclosed by OpenHW | No | | 8 | License text included within the specification text | No - referall only | | 0 | "No-warranty" or disclaimer | Required | +### Specification Version numbers + +OpenHW Specifications shall use semantic versioning https://semver.org/ with the version in the form X.Y.Z. +The version number is combined with the Specification State (below), for example "1.0.0 - Released" to indicate both the version number and state. + + + ### Specification States -The ratification or completion state ais meant to be written in each OpenHW specification so that a reader will be aware of the state of completion of the Specification +The ratification or completion state is meant to be written in each OpenHW specification so that a reader will be aware of the state of completion of the Specification These are the OpenHW Specification States: - “OpenHW Specification - In Development" - "OpenHW Specification - In Review" +- "OpenHW Specification - Release Candidate" - "OpenHW Specification - Released" #### "OpenHW Specification - In Development" When the specification is initiated, all drafts will be labelled as “OpenHW Specification - In Development" +(During initial development of the spec before first release, the version number is of the form X.Y.Z with X=0.) -Revision numbers should be of the form 0.Y.Z +This state is also used when a released spec is subsequently revised. +During revision of a released specifiation, the version number increments as appropriate depending on whether the revision is a major or minor update. #### "OpenHW Specification - In Review" -When the specification is frozen for technical review, all drafts will be labelled as "OpenHW Specification - In Review" +When the specification is frozen for technical review by a Task Group, all drafts will be labelled as "OpenHW Specification - In Review" -Revision numbers should be of the form 0.Y.Z +When the TG(s) has completed its review, the reviewed and stable version will be relabelled as "Release Candidate" - see next section. -#### "OpenHW Specification - Released" +#### "OpenHW Specification - Release Candidate" -When the specification is published, the publication copy will be labelled as "OpenHW Specification - Released" -Revision numbers should be of the form X.Y.Z, starting with 1.0.0 as the initially released version. +When the specification is proposed as a candidate for release, drafts will be labelled as "OpenHW Specification - Release Candidate" + +The complete descriptor of the spec at this stage will be "X.Y.Z - Release Candidate", where X.Y.Z is the proposed release number. + + +#### "OpenHW Specification - Released" -#### "OpenHW Specification Revision" +When a Release Candidate specification has completed ratification (through a TWG vote), the released copy will be labelled as "OpenHW Specification - Released" +Revision numbers should be of the form X.Y.Z, normally starting with X=1 as the initially released version. -Process for labelling and numbering released specifications in revision to be decided. ## Specification Format @@ -109,7 +127,7 @@ The Title should be of the form "OpenHW Specifciation: Title" Prior to release a table of draft revisions should be included, which can included description of content in each draft -Upon release and subsequently, the Revision History should list only released specification versions, starting with 1.0.0. +Upon release, the Revision History should list only released specification versions. That is, intermediate revisisions used during development and review don't need to be listed. The table should include Revision, Date, and Description. The Description should include a high level description of the content. ### Specification States @@ -143,7 +161,7 @@ The following opyright text is included: ### Footer -In cases where the specification is rendered in PDF format, a footer should be included on each page, including OpenHW “Specification Title” and "Copyright © YEAR OF PUBLICATION OpenHW Group" +In cases where the specification is rendered in PDF format, a footer should be included on each page, including OpenHW “Specification Title”, Revision Number/State, and "Copyright © YEAR OF PUBLICATION OpenHW Group" From 233dd46560bbc8b4c23ef517005bd6c95456e326 Mon Sep 17 00:00:00 2001 From: DBees Date: Mon, 15 Jan 2024 16:52:13 -0800 Subject: [PATCH 3/9] Adding text to distinguish "specification" from requirements specification normally used in Open HW open-source projects --- process/OpenHW-Specification-Process.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/process/OpenHW-Specification-Process.md b/process/OpenHW-Specification-Process.md index d653e7d89..26d06e8e8 100644 --- a/process/OpenHW-Specification-Process.md +++ b/process/OpenHW-Specification-Process.md @@ -15,10 +15,17 @@ The V1.0 of this document reflects the agreements made at that meeting and adds ### Overview -OpenHW uses a lightweight specification development process to produce specification documents that are developed and frozen in a designated Task Group, then ratified and released by TWG. +OpenHW uses a lightweight specification development process to produce specification documents (which are similar to standards documents). Such "specifications" convey, for instance: + - Protocol/functionality of an interface to ensure interopability across the interface + - Naming convention such as mmemonic for an instruction class + +This type of specification is developed and frozen in a Task Group designated by the Techinical Working Group (TWG) to this task, then ratified and released (published) by TWG. -### Requirements for OpenHW Specification Process +Note that this process does not refer to a requirements specification for an OpenHW project such as an open-source Core or Hardware or Software project. In that context, requirements specification is a list of the required features of the open-source project. +### Characteristics of the OpenHW Specification Process + +This section describes the characteristics of the Specification Process. This is background information that explains how the process was designed. Those looking to use the process are free to skip reading this section. #### Basics From 1a86771d57cda631350e166b5491663f5d4079cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Qu=C3=A9vremont?= Date: Fri, 19 Jan 2024 18:30:16 +0100 Subject: [PATCH 4/9] Minor fixes Detailed some abbreviations. Used our long name "OpenHW Group" in an "official" document Commons -> Creative Commons Several typos --- process/OpenHW-Specification-Process.md | 88 ++++++++++++------------- 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/process/OpenHW-Specification-Process.md b/process/OpenHW-Specification-Process.md index 26d06e8e8..269ca628d 100644 --- a/process/OpenHW-Specification-Process.md +++ b/process/OpenHW-Specification-Process.md @@ -1,9 +1,9 @@ -# OpenHW Process Document: Specification Process, States and Format +# OpenHW Group Process Document: Specification Process, States and Format ## Revision History -This document desbribes OpenHW's specification process and format. -The overall approach was adopted by consensus in the TWG meeting of July 2023 based on power point presentations and other documents. +This document describes OpenHW Group's specification process and format. +The overall approach was adopted by consensus in the TWG meeting of July 2023 based on PowerPoint presentations and other documents. The V1.0 of this document reflects the agreements made at that meeting and adds additional details. @@ -15,15 +15,15 @@ The V1.0 of this document reflects the agreements made at that meeting and adds ### Overview -OpenHW uses a lightweight specification development process to produce specification documents (which are similar to standards documents). Such "specifications" convey, for instance: +OpenHW Group uses a lightweight specification development process to produce specification documents (which are similar to standards documents). Such "specifications" convey, for instance: - Protocol/functionality of an interface to ensure interopability across the interface - - Naming convention such as mmemonic for an instruction class + - Naming convention such as mnemonic for an instruction class -This type of specification is developed and frozen in a Task Group designated by the Techinical Working Group (TWG) to this task, then ratified and released (published) by TWG. +This type of specification is developed and frozen in a Task Group designated by the Technical Working Group (TWG) to this task, then ratified and released (published) by TWG. -Note that this process does not refer to a requirements specification for an OpenHW project such as an open-source Core or Hardware or Software project. In that context, requirements specification is a list of the required features of the open-source project. +Note that this process does not refer to a requirements specification for an OpenHW Group project such as an open-source Core or Hardware or Software project. In that context, requirements specification is a list of the required features of the open-source project. -### Characteristics of the OpenHW Specification Process +### Characteristics of the OpenHW Group Specification Process This section describes the characteristics of the Specification Process. This is background information that explains how the process was designed. Those looking to use the process are free to skip reading this section. @@ -32,7 +32,7 @@ This section describes the characteristics of the Specification Process. This is | Number | Issue | Comment | | :--- | :------ | :-------------------------------------------------------------------------------- | | 1 | Nature of an OpenHW Group specification | A collective derivative work from the individual member contributions, together with staff contributions | -| 2 | Editors of the specification | OpenHW via its members and staff | +| 2 | Editors of the specification | OpenHW Group via its members and staff | | 3 | Contributions by non-members | For further study | | 4 | Eclipse Specification Process | Not used | @@ -40,95 +40,95 @@ This section describes the characteristics of the Specification Process. This is | Number | Issue | Comment | | :--- | :------ | :-------------------------------------------------------------------------------- | -| 1 | Licenses accepted for contributions to OpenHW Specs | | -| 1.1 | Apache 2.0 | As per OpenHW Member Agreement, contributions can be made using this license | -| 1.2 | Solderpad 2.1 | As per OpenHW Member Agreement, contributions can be made using this license | -| 1.3 | Commons Attribution Share Alike 4.0 International license | Agreed by OpenHW CEO April 2023 | +| 1 | Licenses accepted for contributions to OpenHW Group Specifications | | +| 1.1 | Apache 2.0 | As per OpenHW Group Member Agreement, contributions can be made using this license | +| 1.2 | Solderpad 2.1 | As per OpenHW Group Member Agreement, contributions can be made using this license | +| 1.3 | Creative Commons Attribution Share Alike 4.0 International license | Agreed by OpenHW Group CEO April 2023 | | 2 | Patent Grant included in contribution license: | | | 2.1 | Apache 2.0 | Yes, patent grant included in contributions | | 2.2 | Solderpad 2.1 | Yes, patent grant included in contributions | -| 2.3 | Commons Attribution Share Alike 4.0 International | No patent grant included | +| 2.3 | Creative Commons Attribution Share Alike 4.0 International | No patent grant included | | 3 | Essential patents must be disclosed by contributor | No, Contributors are not required to disclose essential patents | | 4 | Copyright Grant included in contribution license: | | | 4.1 | Apache 2.0 | Yes, copyright grant included in contributions | | 4.2 | Solderpad 2.1 | Yes, copyright grant included in contributions | -| 4.3 | Commons Attribution Share Alike 4.0 International | Yes, copyright grant included in contributions | -| 4 | Contribution Process | Follows EDP/ Committers merging pull requests / Contributors sign ECA or MCCA | +| 4.3 | Creative Commons Attribution Share Alike 4.0 International | Yes, copyright grant included in contributions | +| 4 | Contribution Process | Follows Eclipse Development Process (EDP) / Committers merging pull requests / Contributors sign Eclipse Contributor Agreement (ECA) or Member Committer and Contributor Agreement (MCCA) | #### Publication of the Specification | Number | Issue | Comment | | :--- | :------ | :-------------------------------------------------------------------------------- | -| 1 | Specification published by | OpenHW on Github and/or ReadtheDocs and/or website | -| 2 | Copyright holder on specification | OpenHW on behalf of contributors (member), who hold the copyright jointly. | +| 1 | Specification published by | OpenHW Group on Github and/or ReadtheDocs and/or website | +| 2 | Copyright holder on specification | OpenHW Group on behalf of contributors (member), who hold the copyright jointly. | | 3 | License used for publication | Same license as used for contributions | | 4 | Copyright Grant included in specification publication | As per publication license: | -| 5.1 | Apache 2.0 | Yes, copyright grant included with OpenHW publication | -| 5.2 | Solderpad 2.1 | Yes, copyright grant included with OpenHW publication | -| 5.3 | Commons Attribution Share Alike 4.0 International license | Yes, copyright grant included with OpenHW publication | +| 5.1 | Apache 2.0 | Yes, copyright grant included with OpenHW Group publication | +| 5.2 | Solderpad 2.1 | Yes, copyright grant included with OpenHW Group publication | +| 5.3 | Creative Commons Attribution Share Alike 4.0 International license | Yes, copyright grant included with OpenHW Group publication | | 6 | Patent Grant included in specification publication | As per publication license | -| 6.1 | Apache 2.0 | No patent grant provided by OpenHW but patents rights granted under contribution | -| 6.2 | Solderpad 2.1 | No patent grant provided by OpenHW but patents rights granted under contribution | -| 6.3 | Commons Attribution Share Alike 4.0 International license | No patent grant included with OpenHW publication | -| 7 | Essential patents disclosed by OpenHW | No | +| 6.1 | Apache 2.0 | No patent grant provided by OpenHW Group but patents rights granted under contribution | +| 6.2 | Solderpad 2.1 | No patent grant provided by OpenHW Group but patents rights granted under contribution | +| 6.3 | Creative Commons Attribution Share Alike 4.0 International license | No patent grant included with OpenHW Group publication | +| 7 | Essential patents disclosed by OpenHW Group | No | | 8 | License text included within the specification text | No - referall only | | 0 | "No-warranty" or disclaimer | Required | ### Specification Version numbers -OpenHW Specifications shall use semantic versioning https://semver.org/ with the version in the form X.Y.Z. +OpenHW Group Specifications shall use semantic versioning https://semver.org/ with the version in the form X.Y.Z. The version number is combined with the Specification State (below), for example "1.0.0 - Released" to indicate both the version number and state. ### Specification States -The ratification or completion state is meant to be written in each OpenHW specification so that a reader will be aware of the state of completion of the Specification -These are the OpenHW Specification States: +The ratification or completion state is meant to be written in each OpenHW Group specification so that a reader will be aware of the state of completion of the Specification +These are the OpenHW Group Specification States: -- “OpenHW Specification - In Development" -- "OpenHW Specification - In Review" -- "OpenHW Specification - Release Candidate" -- "OpenHW Specification - Released" +- “OpenHW Group Specification - In Development" +- "OpenHW Group Specification - In Review" +- "OpenHW Group Specification - Release Candidate" +- "OpenHW Group Specification - Released" -#### "OpenHW Specification - In Development" +#### "OpenHW Group Specification - In Development" -When the specification is initiated, all drafts will be labelled as “OpenHW Specification - In Development" +When the specification is initiated, all drafts will be labelled as “OpenHW Group Specification - In Development" (During initial development of the spec before first release, the version number is of the form X.Y.Z with X=0.) This state is also used when a released spec is subsequently revised. During revision of a released specifiation, the version number increments as appropriate depending on whether the revision is a major or minor update. -#### "OpenHW Specification - In Review" +#### "OpenHW Group Specification - In Review" -When the specification is frozen for technical review by a Task Group, all drafts will be labelled as "OpenHW Specification - In Review" +When the specification is frozen for technical review by a Task Group, all drafts will be labelled as "OpenHW Group Specification - In Review" When the TG(s) has completed its review, the reviewed and stable version will be relabelled as "Release Candidate" - see next section. -#### "OpenHW Specification - Release Candidate" +#### "OpenHW Group Specification - Release Candidate" -When the specification is proposed as a candidate for release, drafts will be labelled as "OpenHW Specification - Release Candidate" +When the specification is proposed as a candidate for release, drafts will be labelled as "OpenHW Group Specification - Release Candidate" The complete descriptor of the spec at this stage will be "X.Y.Z - Release Candidate", where X.Y.Z is the proposed release number. -#### "OpenHW Specification - Released" +#### "OpenHW Group Specification - Released" -When a Release Candidate specification has completed ratification (through a TWG vote), the released copy will be labelled as "OpenHW Specification - Released" +When a Release Candidate specification has completed ratification (through a TWG vote), the released copy will be labelled as "OpenHW Group Specification - Released" Revision numbers should be of the form X.Y.Z, normally starting with X=1 as the initially released version. ## Specification Format -The following sections must be included in the OpenHW Specification +The following sections must be included in the OpenHW Group Specification ### Title -The Title should be of the form "OpenHW Specifciation: Title" +The Title should be of the form "OpenHW Group Specifciation: Title" ### Revision History @@ -141,7 +141,7 @@ The table should include Revision, Date, and Description. The Description should The specification state must be listed, e.g. -'The state of this specification is "OpenHW Specification - Released"' +'The state of this specification is "OpenHW Group Specification - Released"' ### License @@ -168,7 +168,7 @@ The following opyright text is included: ### Footer -In cases where the specification is rendered in PDF format, a footer should be included on each page, including OpenHW “Specification Title”, Revision Number/State, and "Copyright © YEAR OF PUBLICATION OpenHW Group" +In cases where the specification is rendered in PDF format, a footer should be included on each page, including OpenHW Group “Specification Title”, Revision Number/State, and "Copyright © YEAR OF PUBLICATION OpenHW Group" From 4918374bb7ef2e6d9a5fd35188d94b479e29d7db Mon Sep 17 00:00:00 2001 From: DBees Date: Tue, 23 Jan 2024 18:01:16 -0800 Subject: [PATCH 5/9] Spell check --- process/OpenHW-Specification-Process.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/process/OpenHW-Specification-Process.md b/process/OpenHW-Specification-Process.md index 26d06e8e8..86e8cc663 100644 --- a/process/OpenHW-Specification-Process.md +++ b/process/OpenHW-Specification-Process.md @@ -2,7 +2,7 @@ ## Revision History -This document desbribes OpenHW's specification process and format. +This document describes OpenHW's specification process and format. The overall approach was adopted by consensus in the TWG meeting of July 2023 based on power point presentations and other documents. The V1.0 of this document reflects the agreements made at that meeting and adds additional details. @@ -16,10 +16,10 @@ The V1.0 of this document reflects the agreements made at that meeting and adds ### Overview OpenHW uses a lightweight specification development process to produce specification documents (which are similar to standards documents). Such "specifications" convey, for instance: - - Protocol/functionality of an interface to ensure interopability across the interface - - Naming convention such as mmemonic for an instruction class + - Protocol/functionality of an interface to ensure interoperability across the interface + - Naming convention such as mnemonic for an instruction class -This type of specification is developed and frozen in a Task Group designated by the Techinical Working Group (TWG) to this task, then ratified and released (published) by TWG. +This type of specification is developed and frozen in a Task Group designated by the Technical Working Group (TWG) to this task, then ratified and released (published) by TWG. Note that this process does not refer to a requirements specification for an OpenHW project such as an open-source Core or Hardware or Software project. In that context, requirements specification is a list of the required features of the open-source project. @@ -72,7 +72,7 @@ This section describes the characteristics of the Specification Process. This is | 6.2 | Solderpad 2.1 | No patent grant provided by OpenHW but patents rights granted under contribution | | 6.3 | Commons Attribution Share Alike 4.0 International license | No patent grant included with OpenHW publication | | 7 | Essential patents disclosed by OpenHW | No | -| 8 | License text included within the specification text | No - referall only | +| 8 | License text included within the specification text | No - referral only | | 0 | "No-warranty" or disclaimer | Required | @@ -100,7 +100,7 @@ When the specification is initiated, all drafts will be labelled as “OpenHW Sp This state is also used when a released spec is subsequently revised. -During revision of a released specifiation, the version number increments as appropriate depending on whether the revision is a major or minor update. +During revision of a released specification, the version number increments as appropriate depending on whether the revision is a major or minor update. #### "OpenHW Specification - In Review" @@ -128,13 +128,13 @@ The following sections must be included in the OpenHW Specification ### Title -The Title should be of the form "OpenHW Specifciation: Title" +The Title should be of the form "OpenHW Specification: Title" ### Revision History Prior to release a table of draft revisions should be included, which can included description of content in each draft -Upon release, the Revision History should list only released specification versions. That is, intermediate revisisions used during development and review don't need to be listed. +Upon release, the Revision History should list only released specification versions. That is, intermediate revisions used during development and review don't need to be listed. The table should include Revision, Date, and Description. The Description should include a high level description of the content. ### Specification States @@ -162,7 +162,7 @@ The following no-warranty text is included: "Unless required by applicable law or agreed to in writing, this Specification and any accompanying software or hardware distributed under the License are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License." ### Copyright -The following opyright text is included: +The following copyright text is included: "Copyright © YEAR OF PUBLICATION OpenHW Group. You may use, copy, modify, and distribute this work under the terms of the License, subject to the conditions specified in the License." From 7d4c7b51aaf1f52981e7461f15a929e54d196bf2 Mon Sep 17 00:00:00 2001 From: DBees Date: Wed, 24 Jan 2024 15:55:06 -0800 Subject: [PATCH 6/9] Embedded State in Title, 1 state optional, described release process --- process/OpenHW-Specification-Process.md | 59 +++++++++++++------------ 1 file changed, 31 insertions(+), 28 deletions(-) diff --git a/process/OpenHW-Specification-Process.md b/process/OpenHW-Specification-Process.md index b05dffaa7..fbbb83252 100644 --- a/process/OpenHW-Specification-Process.md +++ b/process/OpenHW-Specification-Process.md @@ -1,15 +1,15 @@ # OpenHW Group Process Document: Specification Process, States and Format -## Revision History +## Revision History of This Document This document describes OpenHW Group's specification process and format. The overall approach was adopted by consensus in the TWG meeting of July 2023 based on power point presentations and other documents. The V1.0 of this document reflects the agreements made at that meeting and adds additional details. -| Date | Version | Notes | +| Date | Revision | Notes | | :---------- | :------ | :-------------------------------------------------------- | -| 22 Jan 2024 | 1.0 | Formal draft reflecting July 2023 TWG meeting materials | +| 24 Jan 2024 | 1.0.0 | Reflecting July 2023 TWG meeting materials and subsequent review on Github| ## Specification Process @@ -21,7 +21,7 @@ OpenHW uses a lightweight specification development process to produce specifica This type of specification is developed and frozen in a Task Group designated by the Technical Working Group (TWG) to this task, then ratified and released (published) by TWG. -Note that this process does not refer to a requirements specification for an OpenHW Group project such as an open-source Core or Hardware or Software project. In that context, requirements specification is a list of the required features of the open-source project. +Note that this process does not refer to a "requirements specification" for an OpenHW Group project such as an open-source Core or Hardware or Software project. In that context, "requirements specification" is a list of the required features of the open-source project. ### Characteristics of the OpenHW Group Specification Process @@ -61,7 +61,7 @@ This section describes the characteristics of the Specification Process. This is | Number | Issue | Comment | | :--- | :------ | :-------------------------------------------------------------------------------- | | 1 | Specification published by | OpenHW Group on Github and/or ReadtheDocs and/or website | -| 2 | Copyright holder on specification | OpenHW Group on behalf of contributors (member), who hold the copyright jointly. | +| 2 | Copyright holder on specification | OpenHW Group on behalf of contributors (members), who hold the copyright jointly. | | 3 | License used for publication | Same license as used for contributions | | 4 | Copyright Grant included in specification publication | As per publication license: | | 5.1 | Apache 2.0 | Yes, copyright grant included with OpenHW Group publication | @@ -76,50 +76,59 @@ This section describes the characteristics of the Specification Process. This is | 9 | "No-warranty" or disclaimer | Required | -### Specification Version numbers +### Specification Revision Numbers -OpenHW Group Specifications shall use semantic versioning https://semver.org/ with the version in the form X.Y.Z. -The version number is combined with the Specification State (below), for example "1.0.0 - Released" to indicate both the version number and state. +OpenHW Group Specifications shall use semantic versioning https://semver.org/ with the Revision in the form X.Y.Z. +The Revision number is combined with the Specification State (below), for example "1.0.0 - Released" to indicate both the Revision number and State. ### Specification States -The ratification or completion state is meant to be written in each OpenHW Group specification so that a reader will be aware of the state of completion of the Specification +The ratification or completion State is meant to be written together with the Title and Revision in each OpenHW Group specification so that a reader will be aware of the state of completion of the Specification. These are the OpenHW Group Specification States: - “OpenHW Group Specification - In Development" -- "OpenHW Group Specification - In Review" +- "OpenHW Group Specification - In Review" (optional) - "OpenHW Group Specification - Release Candidate" - "OpenHW Group Specification - Released" #### "OpenHW Group Specification - In Development" -When the specification is initiated, all drafts will be labelled as “OpenHW Group Specification - In Development" -(During initial development of the spec before first release, the version number is of the form X.Y.Z with X=0.) +When the specification is initiated, all drafts will be entitled "OpenHW Group Specification: Title : VX.Y.Z : In Development" +(During initial development of the spec before first release, the Revision number is of the form X.Y.Z with X=0.) This state is also used when a released spec is subsequently revised. -During revision of a released specification, the version number increments as appropriate depending on whether the revision is a major or minor update. +During revision of a released specification, the Revision number increments as appropriate depending on whether the revision is a major or minor update. #### "OpenHW Group Specification - In Review" -When the specification is frozen for technical review by a Task Group, all drafts will be labelled as "OpenHW Group Specification - In Review" +This state is optional; see the note below. + +When the specification is frozen for technical review by a Task Group, all drafts will be entitled "OpenHW Group Specification: Title : VX.Y.Z : In Review" +When the TG(s) has completed its review, the reviewed and stable Revision will be relabelled as "Release Candidate" - see next section. + +NOTE: This state can be bypassed if a Task Group does not require a review stage. That is, the TG can move the spec from "In Development" to "Release Candidate". -When the TG(s) has completed its review, the reviewed and stable version will be relabelled as "Release Candidate" - see next section. #### "OpenHW Group Specification - Release Candidate" -When the specification is proposed as a candidate for release, drafts will be labelled as "OpenHW Group Specification - Release Candidate" +When the specification is proposed as a candidate for release, drafts will be entitled "OpenHW Group Specification: Title : VX.Y.Z : Release Candidate" -The complete descriptor of the spec at this stage will be "X.Y.Z - Release Candidate", where X.Y.Z is the proposed release number. +The Revision number used at this stage would normally be same as the proposed Revision to be released. + +The Release Candidate specification will be notified as open for review to the OpenHW TWG. +Although technical comments are expected to have been resolved by the TG, comments may still be accepted at this stage. +After a suitable review period, the TWG Chair/Co-Chair will determine that the Specification is ready for ballot. #### "OpenHW Group Specification - Released" -When a Release Candidate specification has completed ratification (through a TWG vote), the released copy will be labelled as "OpenHW Group Specification - Released" +When a Release Candidate specification has completed ratification (through a TWG vote), the released copy will be entitled "OpenHW Group Specification: Title : VX.Y.Z : Released" Revision numbers should be of the form X.Y.Z, normally starting with X=1 as the initially released version. +The Github commit corresponding to the Released spec will be listed on the Github page of the specification repo together with the "OpenHW Group Specification: Title : VX.Y.Z : Released" string ## Specification Format @@ -128,20 +137,14 @@ The following sections must be included in the OpenHW Group Specification ### Title -The Title should be of the form "OpenHW Specification: Title" +The Title should be of the form "OpenHW Group Specification: Title : VX.Y.Z : State" ### Revision History Prior to release a table of draft revisions should be included, which can included description of content in each draft -Upon release, the Revision History should list only released specification versions. That is, intermediate revisions used during development and review don't need to be listed. -The table should include Revision, Date, and Description. The Description should include a high level description of the content. - -### Specification States - -The specification state must be listed, e.g. - -'The state of this specification is "OpenHW Group Specification - Released"' +Upon release, the Revision History should list only released specification Revisions. That is, intermediate revisions used during development and review don't need to be listed. +The table should include Revision, State, Date, and Description. The Description should include a high level description of the content. ### License @@ -168,7 +171,7 @@ The following copyright text is included: ### Footer -In cases where the specification is rendered in PDF format, a footer should be included on each page, including OpenHW Group “Specification Title”, Revision Number/State, and "Copyright © YEAR OF PUBLICATION OpenHW Group" +In cases where the specification is rendered in PDF format, a footer should be included on each page, including "OpenHW Group Specification: Title : VX.Y.Z : State", and "Copyright © YEAR OF PUBLICATION OpenHW Group" From 75b7f465d11e743c1a0b755d070059158fe50a37 Mon Sep 17 00:00:00 2001 From: DBees Date: Wed, 24 Jan 2024 16:03:06 -0800 Subject: [PATCH 7/9] typo --- process/OpenHW-Specification-Process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/process/OpenHW-Specification-Process.md b/process/OpenHW-Specification-Process.md index fbbb83252..4626be881 100644 --- a/process/OpenHW-Specification-Process.md +++ b/process/OpenHW-Specification-Process.md @@ -141,7 +141,7 @@ The Title should be of the form "OpenHW Group Specification: Title : VX.Y.Z : St ### Revision History -Prior to release a table of draft revisions should be included, which can included description of content in each draft +Prior to release a table of draft revisions should be included, which can include description of content in each draft Upon release, the Revision History should list only released specification Revisions. That is, intermediate revisions used during development and review don't need to be listed. The table should include Revision, State, Date, and Description. The Description should include a high level description of the content. From 4fba8f1668f6e885cf88b1829fef31042b3ed4b7 Mon Sep 17 00:00:00 2001 From: DBees Date: Thu, 8 Feb 2024 19:36:51 -0800 Subject: [PATCH 8/9] Changes from Christian Herber's comments --- process/OpenHW-Specification-Process.md | 84 +++++++++++++++++++++---- 1 file changed, 72 insertions(+), 12 deletions(-) diff --git a/process/OpenHW-Specification-Process.md b/process/OpenHW-Specification-Process.md index 4626be881..6033fdbf9 100644 --- a/process/OpenHW-Specification-Process.md +++ b/process/OpenHW-Specification-Process.md @@ -95,9 +95,12 @@ These are the OpenHW Group Specification States: #### "OpenHW Group Specification - In Development" -When the specification is initiated, all drafts will be entitled "OpenHW Group Specification: Title : VX.Y.Z : In Development" +When the specification is initiated, all drafts will be entitled "OpenHW Group Specification: Title : vX.Y.Z : In Development" (During initial development of the spec before first release, the Revision number is of the form X.Y.Z with X=0.) +NOTE: if the specific template used for publication would repeat the version number if vX.Y.Z is included as part of the title, it may be omitted, as long as the version number is prominently visible in the specification front matter. + + This state is also used when a released spec is subsequently revised. During revision of a released specification, the Revision number increments as appropriate depending on whether the revision is a major or minor update. @@ -106,15 +109,19 @@ During revision of a released specification, the Revision number increments as a This state is optional; see the note below. -When the specification is frozen for technical review by a Task Group, all drafts will be entitled "OpenHW Group Specification: Title : VX.Y.Z : In Review" +When the specification is frozen for technical review by a Task Group, all drafts will be entitled "OpenHW Group Specification: Title : vX.Y.Z : In Review" When the TG(s) has completed its review, the reviewed and stable Revision will be relabelled as "Release Candidate" - see next section. +See note above about version numbering as part of the title. + NOTE: This state can be bypassed if a Task Group does not require a review stage. That is, the TG can move the spec from "In Development" to "Release Candidate". #### "OpenHW Group Specification - Release Candidate" -When the specification is proposed as a candidate for release, drafts will be entitled "OpenHW Group Specification: Title : VX.Y.Z : Release Candidate" +When the specification is proposed as a candidate for release, drafts will be entitled "OpenHW Group Specification: Title : vX.Y.Z : Release Candidate" + +See note above about version numbering as part of the title. The Revision number used at this stage would normally be same as the proposed Revision to be released. @@ -128,16 +135,29 @@ After a suitable review period, the TWG Chair/Co-Chair will determine that the S When a Release Candidate specification has completed ratification (through a TWG vote), the released copy will be entitled "OpenHW Group Specification: Title : VX.Y.Z : Released" Revision numbers should be of the form X.Y.Z, normally starting with X=1 as the initially released version. +See note above about version numbering as part of the title. + The Github commit corresponding to the Released spec will be listed on the Github page of the specification repo together with the "OpenHW Group Specification: Title : VX.Y.Z : Released" string +## File Name for specification + +The following file name should be used for the PDF version of the specification file + +OpenHW_Group_Specification{title_with_underscores}_vX.Y.Z + +An example is as follows: + +OpenHW_Group_Specification_Core-V_eXtension_interface_(CV-X-IF)v1.0.0, i.e. OpenHW_Group_Specification{title_with_underscores}_vX.Y.Z + + ## Specification Format The following sections must be included in the OpenHW Group Specification ### Title -The Title should be of the form "OpenHW Group Specification: Title : VX.Y.Z : State" +The Title should be of the form "OpenHW Group Specification: Title : vX.Y.Z : State" ### Revision History @@ -151,18 +171,58 @@ The table should include Revision, State, Date, and Description. The Description The Publication License is listed, together with a URL link to the source of the license. +The following are examples of appropriate license statement. + +#### Solderpad 0.51 + + +Include "SPDX SHL-0.51" +Include the following license statement taken from https://spdx.org/licenses/SHL-0.51.html: + + +Copyright [yyyy] [OpenHW Group] Copyright and related rights are licensed under the Solderpad Hardware License, Version 0.51 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://solderpad.org/licenses/SHL-0.51. Unless required by applicable law or agreed to in writing, software, hardware and materials distributed under this License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. + + +#### Apache 2.0 + +Include "SPDX Apache-2.0" +Include the following license statement taken from https://spdx.org/licenses/Apache-2.0.html: + + +Copyright [yyyy] [OpenHW Group] + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License." + + +#### Creative Commons Attribution Share Alike 4.0 International + +Include "SPDX CC-BY-SA-4.0" +Include the following license statement (note that no standard license header is provided by https://spdx.org/licenses/CC-BY-SA-4.0.html): + +Copyright [yyyy] [OpenHW Group] -The following is an example of an appropriate license statement: +Licensed under the Creative Commons Attribution Share Alike 4.0 International, (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at -" -Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at +https://spdx.org/licenses/CC-BY-SA-4.0.html - http://www.apache.org/licenses/LICENSE-2.0 +As stated in the License: Disclaimer of Warranties and Limitation of Liability. -### No-warranty -The following no-warranty text is included: +a. Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You. +b. To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You. +c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability. -"Unless required by applicable law or agreed to in writing, this Specification and any accompanying software or hardware distributed under the License are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License." ### Copyright The following copyright text is included: @@ -171,7 +231,7 @@ The following copyright text is included: ### Footer -In cases where the specification is rendered in PDF format, a footer should be included on each page, including "OpenHW Group Specification: Title : VX.Y.Z : State", and "Copyright © YEAR OF PUBLICATION OpenHW Group" +In cases where the specification is rendered in PDF format, a footer should be included, if practical in the documentation template used, on each page, including "OpenHW Group Specification: Title : VX.Y.Z : State", and "Copyright © YEAR OF PUBLICATION OpenHW Group" From dff5cfa01e3ea0eb251d0be1ae6a90d927249fa7 Mon Sep 17 00:00:00 2001 From: DBees Date: Wed, 21 Feb 2024 16:58:18 -0800 Subject: [PATCH 9/9] Changing to -postfix instead of Release State. Clarifications on joint vs collective work. Comments via email from Wayne Beaton. --- process/OpenHW-Specification-Process.md | 100 ++++++++++++++---------- 1 file changed, 59 insertions(+), 41 deletions(-) diff --git a/process/OpenHW-Specification-Process.md b/process/OpenHW-Specification-Process.md index 6033fdbf9..5c2c0540d 100644 --- a/process/OpenHW-Specification-Process.md +++ b/process/OpenHW-Specification-Process.md @@ -1,3 +1,19 @@ +Copyright [2024] [OpenHW Group] + +SPDX Apache-2.0 +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License + + # OpenHW Group Process Document: Specification Process, States and Format ## Revision History of This Document @@ -10,6 +26,7 @@ The V1.0 of this document reflects the agreements made at that meeting and adds | Date | Revision | Notes | | :---------- | :------ | :-------------------------------------------------------- | | 24 Jan 2024 | 1.0.0 | Reflecting July 2023 TWG meeting materials and subsequent review on Github| +| 26 Feb 2024 | 1.1.0 | Version made available for TWG meeting of Feb 26 2024 | ## Specification Process @@ -31,45 +48,46 @@ This section describes the characteristics of the Specification Process. This is | Number | Issue | Comment | | :--- | :------ | :-------------------------------------------------------------------------------- | -| 1 | Nature of an OpenHW Group specification | A collective derivative work from the individual member contributions, together with staff contributions | +| 1 | Nature of an OpenHW Group specification | A joint work or collective derivative work from the individual member contributions, together with staff contributions | | 2 | Editors of the specification | OpenHW Group via its members and staff | | 3 | Contributions by non-members | For further study | | 4 | Eclipse Specification Process | Not used | -#### Contributions into the Specification +#### Contributions into an OpenHW Specification | Number | Issue | Comment | | :--- | :------ | :-------------------------------------------------------------------------------- | -| 1 | Licenses accepted for contributions to OpenHW Group Specifications | | -| 1.1 | Apache 2.0 | As per OpenHW Group Member Agreement, contributions can be made using this license | -| 1.2 | Solderpad 2.1 | As per OpenHW Group Member Agreement, contributions can be made using this license | -| 1.3 | Creative Commons Attribution Share Alike 4.0 International license | Agreed by OpenHW Group CEO April 2023 | -| 2 | Patent Grant included in contribution license: | | -| 2.1 | Apache 2.0 | Yes, patent grant included in contributions | -| 2.2 | Solderpad 2.1 | Yes, patent grant included in contributions | -| 2.3 | Creative Commons Attribution Share Alike 4.0 International | No patent grant included | -| 3 | Essential patents must be disclosed by contributor | No, Contributors are not required to disclose essential patents | -| 4 | Copyright Grant included in contribution license: | | -| 4.1 | Apache 2.0 | Yes, copyright grant included in contributions | -| 4.2 | Solderpad 2.1 | Yes, copyright grant included in contributions | -| 4.3 | Creative Commons Attribution Share Alike 4.0 International | Yes, copyright grant included in contributions | -| 5 | Contribution Process | Follows Eclipse Development Process (EDP) / Committers merging pull requests / Contributors sign Eclipse Contributor Agreement (ECA) or Member Committer and Contributor Agreement (MCCA) | - - -#### Publication of the Specification +| 1 | OpenHW Member Agreement | Member agreement Section 3.4 details the license granted on contributions to OpenHW Group allowing OpenHW Group to copy, create and publish derivative works, and other related rights | +| 2 | Licenses accepted for contributions to OpenHW Group Specifications | | +| 2.1 | Apache 2.0 | As per OpenHW Group Member Agreement, contributions can be made using this license | +| 2.2 | Solderpad 2.1 | As per OpenHW Group Member Agreement, contributions can be made using this license | +| 2.3 | Creative Commons Attribution Share Alike 4.0 International license | Agreed by OpenHW Group CEO April 2023 | +| 3 | Patent Grant included in contribution license: | | +| 3.1 | Apache 2.0 | Yes, patent grant included in contributions | +| 3.2 | Solderpad 2.1 | Yes, patent grant included in contributions | +| 3.3 | Creative Commons Attribution Share Alike 4.0 International | No patent grant included | +| 4 | Essential patents must be disclosed by contributor | No, Contributors are not required to disclose essential patents | +| 5 | Copyright Grant included in contribution license: | | +| 5.1 | Apache 2.0 | Yes, copyright license grant included in contributions | +| 5.2 | Solderpad 2.1 | Yes, copyright license grant included in contributions | +| 5.3 | Creative Commons Attribution Share Alike 4.0 International | Yes, copyright grant included in contributions | +| 6 | Contribution Process | Follows Eclipse Development Process (EDP) / Committers merging pull requests / Contributors sign Eclipse Contributor Agreement (ECA) or Member Committer and Contributor Agreement (MCCA) | + + +#### Publication of a Specification by OpenHW | Number | Issue | Comment | | :--- | :------ | :-------------------------------------------------------------------------------- | | 1 | Specification published by | OpenHW Group on Github and/or ReadtheDocs and/or website | -| 2 | Copyright holder on specification | OpenHW Group on behalf of contributors (members), who hold the copyright jointly. | +| 2 | Copyright holder on specification | OpenHW Group on behalf of contributors (members), who retain the copyright on their individual contributions | | 3 | License used for publication | Same license as used for contributions | | 4 | Copyright Grant included in specification publication | As per publication license: | | 5.1 | Apache 2.0 | Yes, copyright grant included with OpenHW Group publication | | 5.2 | Solderpad 2.1 | Yes, copyright grant included with OpenHW Group publication | | 5.3 | Creative Commons Attribution Share Alike 4.0 International license | Yes, copyright grant included with OpenHW Group publication | | 6 | Patent Grant included in specification publication | As per publication license | -| 6.1 | Apache 2.0 | No patent grant provided by OpenHW but patents rights granted under contribution | -| 6.2 | Solderpad 2.1 | No patent grant provided by OpenHW but patents rights granted under contribution | +| 6.1 | Apache 2.0 | Patents rights granted by contributors under Apache 2.0 | +| 6.2 | Solderpad 2.1 | Patents rights granted by contributors under Solderpad 2.1 | | 6.3 | Commons Attribution Share Alike 4.0 International license | No patent grant included with OpenHW publication | | 7 | Essential patents disclosed by OpenHW | No | | 8 | License text included within the specification text | No - referral only | @@ -78,25 +96,25 @@ This section describes the characteristics of the Specification Process. This is ### Specification Revision Numbers -OpenHW Group Specifications shall use semantic versioning https://semver.org/ with the Revision in the form X.Y.Z. -The Revision number is combined with the Specification State (below), for example "1.0.0 - Released" to indicate both the Revision number and State. +OpenHW Group Specifications shall use semantic versioning https://semver.org/ with the Revision in the form vX.Y.Z-postfix +The Revision number is combined with the Specification State (below), for example "v1.0.0-rel1" to indicate both the Revision number and State. -### Specification States +### Specification States and postfix The ratification or completion State is meant to be written together with the Title and Revision in each OpenHW Group specification so that a reader will be aware of the state of completion of the Specification. -These are the OpenHW Group Specification States: +These are the OpenHW Group Specification States and corresponding postfixes: -- “OpenHW Group Specification - In Development" -- "OpenHW Group Specification - In Review" (optional) -- "OpenHW Group Specification - Release Candidate" -- "OpenHW Group Specification - Released" +- “In Development". The version postfix is -devW, for example -dev1, -dev2 +- "In Review" (optional). The version postfix is -reviewW, for example -review1, -review2 +- "Release Candidate". The version postfix is -rcW, for example -rc1, -rc2 +- "Released". The version postfix is -relW, for example -re11, -rel2 #### "OpenHW Group Specification - In Development" -When the specification is initiated, all drafts will be entitled "OpenHW Group Specification: Title : vX.Y.Z : In Development" -(During initial development of the spec before first release, the Revision number is of the form X.Y.Z with X=0.) +When the specification is initiated, all drafts will be entitled "OpenHW Group Specification: Title : vX.Y.Z-devW". +(During initial development of the spec before first release, the Revision number is of the form X.Y.Z with X=0). NOTE: if the specific template used for publication would repeat the version number if vX.Y.Z is included as part of the title, it may be omitted, as long as the version number is prominently visible in the specification front matter. @@ -109,8 +127,8 @@ During revision of a released specification, the Revision number increments as a This state is optional; see the note below. -When the specification is frozen for technical review by a Task Group, all drafts will be entitled "OpenHW Group Specification: Title : vX.Y.Z : In Review" -When the TG(s) has completed its review, the reviewed and stable Revision will be relabelled as "Release Candidate" - see next section. +When the specification is frozen for technical review by a Task Group, all drafts will be entitled "OpenHW Group Specification: Title : vX.Y.Z-reviewW". +When the TG(s) has completed its review, the reviewed and stable Revision will be relabelled as "rc" - see next section. See note above about version numbering as part of the title. @@ -119,7 +137,7 @@ NOTE: This state can be bypassed if a Task Group does not require a review stage #### "OpenHW Group Specification - Release Candidate" -When the specification is proposed as a candidate for release, drafts will be entitled "OpenHW Group Specification: Title : vX.Y.Z : Release Candidate" +When the specification is proposed as a candidate for release, drafts will be entitled "OpenHW Group Specification: Title : vX.Y.Z-rcW", See note above about version numbering as part of the title. @@ -132,23 +150,23 @@ After a suitable review period, the TWG Chair/Co-Chair will determine that the S #### "OpenHW Group Specification - Released" -When a Release Candidate specification has completed ratification (through a TWG vote), the released copy will be entitled "OpenHW Group Specification: Title : VX.Y.Z : Released" +When a Release Candidate specification has completed ratification (through a TWG vote), the released copy will be entitled "OpenHW Group Specification: Title : VX.Y.Z-relW". Revision numbers should be of the form X.Y.Z, normally starting with X=1 as the initially released version. See note above about version numbering as part of the title. -The Github commit corresponding to the Released spec will be listed on the Github page of the specification repo together with the "OpenHW Group Specification: Title : VX.Y.Z : Released" string +The Github commit corresponding to the Released spec will be listed on the Github page of the specification repo together with the "OpenHW Group Specification: Title : VX.Y.Z-relW" string ## File Name for specification The following file name should be used for the PDF version of the specification file -OpenHW_Group_Specification{title_with_underscores}_vX.Y.Z +OpenHW_Group_Specification{title_with_underscores}_vX.Y.Z-postfix.pdf An example is as follows: -OpenHW_Group_Specification_Core-V_eXtension_interface_(CV-X-IF)v1.0.0, i.e. OpenHW_Group_Specification{title_with_underscores}_vX.Y.Z +OpenHW_Group_Specification_Core-V_eXtension_interface_(CV-X-IF)v1.0.0-rel1.pdf ## Specification Format @@ -157,7 +175,7 @@ The following sections must be included in the OpenHW Group Specification ### Title -The Title should be of the form "OpenHW Group Specification: Title : vX.Y.Z : State" +The Title should be of the form "OpenHW Group Specification: Title : vX.Y.Z-postfix" ### Revision History @@ -231,7 +249,7 @@ The following copyright text is included: ### Footer -In cases where the specification is rendered in PDF format, a footer should be included, if practical in the documentation template used, on each page, including "OpenHW Group Specification: Title : VX.Y.Z : State", and "Copyright © YEAR OF PUBLICATION OpenHW Group" +In cases where the specification is rendered in PDF format, a footer should be included, if practical in the documentation template used, on each page, including "OpenHW Group Specification: Title : VX.Y.Z-postfix", and "Copyright © YEAR OF PUBLICATION OpenHW Group"