-
Notifications
You must be signed in to change notification settings - Fork 97
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Upload draft of specification process for review #643
base: master
Are you sure you want to change the base?
Changes from 1 commit
758d81c
e07e38c
233dd46
1a86771
4918374
d3ff807
7d4c7b5
75b7f46
4fba8f1
dff5cfa
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. the -rc postfix is separated from its rc version with a dot |
||
- "Released". The version postfix is -relW, for example -re11, -rel2 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. A released version does not have a post-fix |
||
|
||
#### "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" | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. V is still capital here |
||
|
||
|
||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Missing section: Filename requirementes (especially for pdf publication) - template: OpenHW_Group_Specification_Core-V_eXtension_interface_(CV-X-IF)v1.0.0, i.e. OpenHW_Group_Specification{title_with_underscores}_vX.Y.Z |
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
dev and review do not need version numbers beyond the normal version. this is just a special case for release candidates, as they might need to differentiate multiple versions starting with e.g. 1.0.0.
For development versions etc., the main version number would just increment between versions