Skip to content

Commit 758d81c

Browse files
DBeesDBees
committed
Upload draft of specification process for review
1 parent 6dfe587 commit 758d81c

File tree

1 file changed

+152
-0
lines changed

1 file changed

+152
-0
lines changed

‎process/OpenHW-Specification-Process.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# OpenHW Process Document: Specification Process, States and Format
2+
3+
## Revision History
4+
5+
This document desbribes OpenHW's specification process and format.
6+
It was adopted by consensus in the TWG meeting of July 2023.
7+
8+
The V1.0 of this document reflects the agreements made at that meeting and adds additional details.
9+
10+
| Date | Version | Notes |
11+
| :---------- | :------ | :---------------------------------------------------- |
12+
| 22 Jan 2024 | 1.0 | Formal draft reflecting July 2023 google docs |
13+
14+
## Specification Process
15+
16+
### Overview
17+
18+
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.
19+
20+
### Requirements for OpenHW Specification Process
21+
22+
23+
#### Basics
24+
25+
| Number | Issue | Comment |
26+
| :--- | :------ | :-------------------------------------------------------------------------------- |
27+
| 1 | Nature of the specification | A collective derivative work from the individual member contributions, together with staff contributions |
28+
| 2 | Editors of the specification | OpenHW via its members and staff |
29+
| 3 | Contributions by non-members | For further study |
30+
| 4 | Eclipse Specification Process | Not used |
31+
32+
#### Contributions into the Specification
33+
34+
| Number | Issue | Comment |
35+
| :--- | :------ | :-------------------------------------------------------------------------------- |
36+
| 1 | License options for contributions: | |
37+
| 1.1 | Apache 2.0 | As per OpenHW Member Agreement |
38+
| 1.2 | Solderpad 2.1 | As per OpenHW Member Agreement |
39+
| 1.3 | Commons Attribution Share Alike 4.0 International license | Agreed by OpenHW CEO April 2023 |
40+
| 2 | Patent Grant included in contribution license: | |
41+
| 2.1 | Apache 2.0 | Yes |
42+
| 2.2 | Solderpad 2.1 | Yes |
43+
| 2.3 | Commons Attribution Share Alike 4.0 International license | No |
44+
| 3 | Essential patents must be disclosed by contributor | No |
45+
| 4 | Contribution Process | EDP/ Committers merging pull requests / Contributors sign ECA or MCCA |
46+
47+
48+
#### Publication of the Specification
49+
50+
| Number | Issue | Comment |
51+
| :--- | :------ | :-------------------------------------------------------------------------------- |
52+
| 1 | Specification published by | OpenHW on Github and/or ReadtheDocs and/or website |
53+
| 2 | Copyright holder on specification | OpenHW on behalf of contributors (member), who hold the copyright jointly. |
54+
| 3 | License used for publication | Same license as used for contributions |
55+
| 4 | Copyright Grant included in specification publication | As per publication license: }
56+
| 5.1 | Apache 2.0 | Yes |
57+
| 5.2 | Solderpad 2.1 | Yes |
58+
| 5.3 | Commons Attribution Share Alike 4.0 International license | Yes |
59+
| 6 | Patent Grant included in specification publication | As per publication license |
60+
| 6.1 | Apache 2.0 | Yes |
61+
| 6.2 | Solderpad 2.1 | Yes |
62+
| 6.3 | Commons Attribution Share Alike 4.0 International license | No |
63+
| 7 | Essential patents disclosed by OpenHW | No |
64+
| 8 | License text included within the specification text | No - referall only |
65+
| 0 | "No-warranty" or disclaimer | Required |
66+
67+
68+
### Specification States
69+
70+
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
71+
These are the OpenHW Specification States:
72+
73+
- “OpenHW Specification - In Development"
74+
- "OpenHW Specification - In Review"
75+
- "OpenHW Specification - Released"
76+
77+
#### "OpenHW Specification - In Development"
78+
79+
When the specification is initiated, all drafts will be labelled as “OpenHW Specification - In Development"
80+
81+
Revision numbers should be of the form 0.Y.Z
82+
83+
84+
#### "OpenHW Specification - In Review"
85+
86+
When the specification is frozen for technical review, all drafts will be labelled as "OpenHW Specification - In Review"
87+
88+
Revision numbers should be of the form 0.Y.Z
89+
90+
#### "OpenHW Specification - Released"
91+
92+
When the specification is published, the publication copy will be labelled as "OpenHW Specification - Released"
93+
Revision numbers should be of the form X.Y.Z, starting with 1.0.0 as the initially released version.
94+
95+
#### "OpenHW Specification Revision"
96+
97+
Process for labelling and numbering released specifications in revision to be decided.
98+
99+
100+
## Specification Format
101+
102+
The following sections must be included in the OpenHW Specification
103+
104+
### Title
105+
106+
The Title should be of the form "OpenHW Specifciation: Title"
107+
108+
### Revision History
109+
110+
Prior to release a table of draft revisions should be included, which can included description of content in each draft
111+
112+
Upon release and subsequently, the Revision History should list only released specification versions, starting with 1.0.0.
113+
The table should include Revision, Date, and Description. The Description should include a high level description of the content.
114+
115+
### Specification States
116+
117+
The specification state must be listed, e.g.
118+
119+
'The state of this specification is "OpenHW Specification - Released"'
120+
121+
122+
### License
123+
124+
The Publication License is listed, together with a URL link to the source of the license.
125+
126+
127+
The following is an example of an appropriate license statement:
128+
129+
"
130+
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
131+
132+
http://www.apache.org/licenses/LICENSE-2.0
133+
134+
### No-warranty
135+
The following no-warranty text is included:
136+
137+
"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."
138+
139+
### Copyright
140+
The following opyright text is included:
141+
142+
"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."
143+
144+
### Footer
145+
146+
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"
147+
148+
149+
150+
151+
152+

0 commit comments

Comments
 (0)