Upload draft of specification process for review #643
Conversation
DBees
requested review from
jeremybennett,
MikeOpenHWGroup,
jquevremont and
christian-herber-nxp
| ### 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." |
There was a problem hiding this comment.
copyright doesnt start with the publication, but with the development.
@christian-herber-nxp can you break this into a ratified part, then a separate document which is an extension? Once the extension is ratified we can up-issue the ratified part to include the extension. |
|
@christian-herber-nxp @MikeOpenHWGroup new version uploaded |
| @@ -0,0 +1,170 @@ | |||
| # OpenHW Process Document: Specification Process, States and Format | |||
There was a problem hiding this comment.
No process is complete without templates and tools. Recommend to provide a template github project from which to start. I would also question if the Specification Process shouldn't just use its own process, and thus its own template. In this case, you should move from MD to RST
…ation normally used in Open HW open-source projects
Detailed some abbreviations. Used our long name "OpenHW Group" in an "official" document Commons -> Creative Commons Several typos
|
@jquevremont thanks for the review and corrections |
|
@jeremybennett we'll merge this unless you have comments? |
|
@DBees please mark review items as resolved if you updated the text. that gives an overview if everything has been resolved |
Merging Jerome's changes with additional typos and spelling corrections
There was a problem hiding this comment.
There are parts of the specification process which are not practically implementable with the given templates. The current feedback loop doesn't seem to do a good job in concluding this. The specification process has been written top down, but must be bottom up where technical limitations are in place. For CV-X-IF, I will follow the process where possible, and otherwise try to act in the spirit of this process.
CV-X-IF specification can be worked into a documentation template. Without showing a working template, the process is not complete.
|
@christian-herber-nxp yes, already noted that a template will be added to accompany the process document. Yes, please flag things (such as the footer in PDF) that present particular issues and we'll figure it out. |
| ### 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. |
There was a problem hiding this comment.
not always possible. Better to have postfixes (see semver.org) like -rc.1, -dev etc.
|
|
||
| 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. |
There was a problem hiding this comment.
The revision history is generated from the releases on github. There is no control over which versions should be listed.
| 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. |
There was a problem hiding this comment.
again, it is what it is. See any document for what to expect
| 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 |
There was a problem hiding this comment.
SPDX identifier should be given, along with the recommended text from spdx.org for the given license
| ### Copyright | ||
| 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." |
There was a problem hiding this comment.
the second sentence here should be part of the license text, not added to a copyright statement
| 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" | ||
|
|
||
|
|
||
|
|
There was a problem hiding this comment.
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
…t vs collective work. Comments via email from Wayne Beaton.
|
@christian-herber-nxp please review latest in which I changed Specification State to -postfix at your suggestion. Please let me know if the details seem good to you. That would imply that the final version of the spec is published with vx.y.z-rel1 for instance. |
| - “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 |
There was a problem hiding this comment.
A released version does not have a post-fix
| - "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.
the -rc postfix is separated from its rc version with a dot
| - "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 |
There was a problem hiding this comment.
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
| @@ -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.
V is still capital here
There was a problem hiding this comment.
There are several instances now where due to the changes, the CV-X-IF specification is no longer aligned to the specification process. I would have hoped we align the process to the spec, especially as I aligned this to the process where possible. You will check to work with the conf.py I created and the corresponding template to work that out.
No description provided.