Return-Path: virtio-comment-return-1331-cohuck=redhat.com@lists.oasis-open.org Sender: List-Post: List-Help: List-Unsubscribe: List-Subscribe: Received: from lists.oasis-open.org (oasis-open.org [10.110.1.242]) by lists.oasis-open.org (Postfix) with ESMTP id 703C6986135 for ; Fri, 19 Jun 2020 20:50:09 +0000 (UTC) From: =?UTF-8?q?Alex=20Benn=C3=A9e?= Date: Fri, 19 Jun 2020 21:49:55 +0100 Message-Id: <20200619204959.7877-2-alex.bennee@linaro.org> In-Reply-To: <20200619204959.7877-1-alex.bennee@linaro.org> References: <20200619204959.7877-1-alex.bennee@linaro.org> MIME-Version: 1.0 Subject: [virtio-comment] [PATCH v2 1/5] README.md: convert html to proper Markdown format Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable To: virtio-comment@lists.oasis-open.org Cc: =?UTF-8?q?Alex=20Benn=C3=A9e?= , Robin Cover List-ID: There is no point embedding HTML inside the markdown document. It just makes it messy to edit. The boilerplate text is maintained. Signed-off-by: Alex Benn=C3=A9e Cc: Robin Cover --- README.md | 258 +++++++++++++++++++++--------------------------------- 1 file changed, 100 insertions(+), 158 deletions(-) diff --git a/README.md b/README.md index 2bdf485..8bb10e0 100644 --- a/README.md +++ b/README.md @@ -1,173 +1,115 @@ -
-

README

+Members of the [OASIS Virtual I/O Device (VIRTIO) TC](https://www.oasis-op= en.org/committees/virtio/) create and manage technical content in this TC G= itHub repository ( [https://github.com/oasis-tcs/virtio-spec](https://githu= b.com/oasis-tcs/virtio-spec) ) as part of the TC's chartered work (_i.e._, = the program of work and deliverables described in its [charter](https://www= .oasis-open.org/committees/virtio/charter.php)). =20 -

Members of the OASIS Virtual I/O Device (VIRTIO) TC create and manage technical cont= ent in this TC GitHub repository ( https://github.com/oasis-tcs/virtio-spec ) as part of the = TC's chartered work (i.e., the program of work and deliverables desc= ribed in its charter).

+OASIS TC GitHub repositories, as described in [GitHub Repositories for OAS= IS TC Members' Chartered Work](https://www.oasis-open.org/resources/tcadmin= /github-repositories-for-oasis-tc-members-chartered-work), are governed by = the OASIS [TC Process](https://www.oasis-open.org/policies-guidelines/tc-pr= ocess), [IPR Policy](https://www.oasis-open.org/policies-guidelines/ipr), a= nd other policies, similar to TC Wikis, TC JIRA issues tracking instances, = TC SVN/Subversion repositories, etc. While they make use of public GitHub r= epositories, these TC GitHub repositories are distinct from [OASIS Open Rep= ositories](https://www.oasis-open.org/resources/open-repositories), which a= re used for development of open source [licensed](https://www.oasis-open.or= g/resources/open-repositories/licenses) content. =20 -

OASIS TC GitHub repositories, as described in GitHub Repositories for OASIS TC Members' Chartered Work, = are governed by the OASIS TC Process, IPR Policy, and other policies, similar to TC = Wikis, TC JIRA issues tracking instances, TC SVN/Subversion repositories, e= tc. While they make use of public GitHub repositories, these TC GitHub rep= ositories are distinct from OASIS Open Repositories, which are used for develop= ment of open source licensed content.

-
+### Description =20 -
-

Description

+This repository includes the [authoritative source](https://github.com/oas= is-tcs/virtio-spec/releases) of the VIRTIO (Virtual I/O) Specification docu= ment. VIRTIO document describes the specifications of the "virtio" family o= f devices. These devices are found in virtual environments, yet by design t= hey look like physical devices to the guest within the virtual machine =E2= =80=94 and this document treats them as such. This similarity allows the gu= est to use standard drivers and discovery mechanisms. =20 -

This repository includes the authoritative source of the VIRTIO (Virtual I/O) Sp= ecification document. VIRTIO document describes the specifications of the "= virtio" family of devices. These devices are found in virtual environments,= yet by design they look like physical devices to the guest within the virt= ual machine — and this document treats them as such. This similarity = allows the guest to use standard drivers and discovery mechanisms.

+The purpose of virtio and this specification is that virtual environments = and guests should have a straightforward, efficient, standard and extensibl= e mechanism for virtual devices, rather than boutique per-environment or pe= r-OS mechanisms. =20 -

The purpose of virtio and this specification is that virtual environmen= ts and guests should have a straightforward, efficient, standard and extens= ible mechanism for virtual devices, rather than boutique per-environment or= per-OS mechanisms.

-
+### Contributions =20 -
-

Contributions

-

As stated in this repository's CONTRIBUTING file, contributor= s to this repository are expected to be Members of the OASIS virtio TC, for= any substantive change requests. Anyone wishing to contribute to this Git= Hub project and participate in the TC's technical activity is invited to jo= in as an OASIS TC Member. Public feedback is also accepted, subject to the= terms of the OASIS Feedback License.

-
+As stated in this repository's [CONTRIBUTING file](https://github.com/oasi= s-tcs/virtio-spec/blob/master/CONTRIBUTING.md), contributors to this reposi= tory are expected to be Members of the OASIS virtio TC, for any substantive= change requests. Anyone wishing to contribute to this GitHub project and [= participate](https://www.oasis-open.org/join/participation-instructions) in= the TC's technical activity is invited to join as an OASIS TC Member. Publ= ic feedback is also accepted, subject to the terms of the [OASIS Feedback L= icense](https://www.oasis-open.org/policies-guidelines/ipr#appendixa). =20 +### Licensing =20 +Please see the [LICENSE](https://github.com/oasis-tcs/virtio-spec/blob/mas= ter/LICENSE.md) file for description of the license terms and OASIS policie= s applicable to the TC's work in this GitHub project. Content in this repos= itory is intended to be part of the virtio TC's permanent record of activit= y, visible and freely available for all to use, subject to applicable OASIS= policies, as presented in the repository [LICENSE](https://github.com/oasi= s-tcs/virtio-spec/blob/master/LICENSE.md) file. =20 -
-

Licensing

-

Please see the LICENSE file for description of the license terms a= nd OASIS policies applicable to the TC's work in this GitHub project. Conte= nt in this repository is intended to be part of the virtio TC's permanent r= ecord of activity, visible and freely available for all to use, subject to = applicable OASIS policies, as presented in the repository LICENSE file= .

-
+### Further Description of this Repository =20 -
+#### Building Instructions =20 -

Further Description of this Repository

-

Building Instructions

-Authoritative version of the specification is maintained in the -TeX document format. PDF and HTML versions are made available for -ease of use and review. -In order to build the HTML and PDF versions of the spec you will need the -TeX document production system. -The easiest way to get it up and running is probably by installing -Tex-Live. +Authoritative version of the specification is maintained in the TeX docume= nt format. PDF and HTML versions are made available for ease of use and rev= iew. In order to build the HTML and PDF versions of the spec you will need = the TeX document production system. The easiest way to get it up and runnin= g is probably by installing [Tex-Live](https://www.tug.org/texlive/). + +Installation cheat sheet: + +Fedora: + +`sudo dnf install texlive-scheme-full` =20 -
Installation cheat sheet: -
Fedora:
-
- -sudo dnf install texlive-scheme-full -
-
Ubuntu and other Debian derivatives: -
-
- -sudo apt-get install texlive-full -
-
OSX:
-
OSX users don't need to install Tex-Live because they already have -MacTeX installed. -
-
-
The build process generates a ZIP package file including the -original TeX sources, as well as HTML and PDF formatted -versions of the specification. -
To generate the ZIP package, run:
-
- -./makeall.sh - -
-
Troubleshooting notes:
-
PDFs of the specification can be generated with -either MicroSoft's Core fonts for the Web: Arial and Courier New, -or Liberation fonts: Liberation Sans and Liberation Mono. -Most systems come with one of these two variants included: -should you get an error message about missing fonts, -you will need to downloads and install one of the above -font packages. -
-
-

Providing Feedback

-Feedback must be provided the virtio-comment mailing list= , -and archived in the mailing list archives. -

See -https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=3Dvirtio#feedb= ack -

Note that only plain text part of the message is archived, and all -attachments are stripped. Accordingly, messages sent to the -mailing list should use text/plain encoding and not -have any attachments. -

The preferred form of providing feedback is in form of a patch. -A patch can be generated and sent by cloning the spec repository, -creating a commit, formatting it as a patch and then sending it. -For example: - -

-git clone https://github.com/oasis-tcs/virtio-spec.git
-... edit spec text, and save ...
-

-git commit -a
-... describe the proposed change, in the following format:
-single line summary
-
-detailed description, including motivation for the change
-
-Signed-off-by: Name <email>
-... then save and close the editor ...
-

-git format-patch -o proposal1/ HEAD~1..
-... generates a new directory proposal1/ and a file starting with 0001- ..= .
-

-git send-email --to=3Dvirtio-comment@lists.oasis-open.org proposal1/0001-* - -

Note for TC Members

-

TC Members should review TC specific -process rules under "Further Description of this Repository" -in https://github.com/oasi= s-tcs/virtio-admin. - -

-

Implementation discussion

-Implementation discussion should take place on the virtio-dev mailing list, -and be archived in the mailing list archives. -

See -https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=3Dvirtio#feedb= ack -

This is the correct list to copy on Linux virtio UAPI change proposals. -

Note that only the plain text part of the message is archived, and all -attachments are stripped. Accordingly, messages sent to the -mailing list should use text/plain encoding and not -have any attachments. -

Use of github issues

-Note: according to the virtio TC rules, all official TC communication -is taking place on one of the TC mailing lists. -In particular, all comments must be provided on -one of the TC mailing lists. Accordingly, the TC will not respond -to comments provided in github issues: github issues are -used solely to track integration of comments into the -specification.

+ +`sudo apt-get install texlive-full` + +OSX: + +OSX users don't need to install Tex-Live because they already have [MacTeX= ](http://www.tug.org/mactex/) installed. + +The build process generates a ZIP package file including the original TeX = sources, as well as HTML and PDF formatted versions of the specification. + +To generate the ZIP package, run: + +`./makeall.sh` + +Troubleshooting notes: + +PDFs of the specification can be generated with either MicroSoft's Core fo= nts for the Web: Arial and Courier New, or Liberation fonts: Liberation San= s and Liberation Mono. Most systems come with one of these two variants inc= luded: should you get an error message about missing fonts, you will need t= o downloads and install one of the above font packages. + +#### Providing Feedback + +Feedback must be provided the **virtio-comment** mailing list, and archive= d in the mailing list archives. + +See [https://www.oasis-open.org/committees/tc\_home.php?wg\_abbrev=3Dvirti= o#feedback](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=3Dv= irtio#feedback) + +Note that only plain text part of the message is archived, and all attachm= ents are stripped. Accordingly, messages sent to the mailing list should us= e text/plain encoding and not have any attachments. + +The preferred form of providing feedback is in form of a patch. A patch ca= n be generated and sent by cloning the spec repository, creating a commit, = formatting it as a patch and then sending it. For example: + +`git clone https://github.com/oasis-tcs/virtio-spec.git =20 +... edit spec text, and save ... =20 +` + +`git commit -a =20 +... describe the proposed change, in the following format: =20 +single line summary =20 + =20 +detailed description, including motivation for the change =20 + =20 +Signed-off-by: Name =20 +... then save and close the editor ... =20 +` + +`git format-patch -o proposal1/ HEAD~1.. =20 +... generates a new directory proposal1/ and a file starting with 0001- ..= . =20 +` + +`git send-email --to=3Dvirtio-comment@lists.oasis-open.org proposal1/0001-= *` + +#### Note for TC Members + +TC Members should review TC specific process rules under "Further Descript= ion of this Repository" in [https://github.com/oasis-tcs/virtio-admin](http= s://github.com/oasis-tcs/virtio-admin). + +#### Implementation discussion + +Implementation discussion should take place on the **virtio-dev** mailing = list, and be archived in the mailing list archives. + +See [https://www.oasis-open.org/committees/tc\_home.php?wg\_abbrev=3Dvirti= o#feedback](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=3Dv= irtio#feedback) + +This is the correct list to copy on Linux virtio UAPI change proposals. + +Note that only the plain text part of the message is archived, and all att= achments are stripped. Accordingly, messages sent to the mailing list shoul= d use text/plain encoding and not have any attachments. + +#### Use of github issues + +Note: according to the virtio TC rules, all official TC communication is t= aking place on one of the TC mailing lists. In particular, all comments mus= t be provided on one of the TC mailing lists. Accordingly, the TC will not = respond to comments provided in github issues: github issues are used solel= y to track integration of comments into the specification. + To request a TC vote on resolving a specific comment: -

    -
  1. Create a github issue, or edit an existing issue, with -a short summary of the comment. -The issue MUST specify -the link to the latest proposal in the TC mailing list -archives. Note: the link MUST be in the issue description itself = - -not in the comments.
  2. -
  3. Reply by email to the comment email, requesting that the TC vote -on resolving the issue. -The mail requesting the vote should include the following, on a line by it= self:
    - -Fixes: https://github.com/oasis-tcs/virtio-spec/issues/NNN - -(NNN is the issue number)
  4. -
  5. Please make sure to allow time for review between posting a comment -and asking for a vote.
  6. -
-

TC standing rules

+ +1. Create a github issue, or edit an existing issue, with a short summary= of the comment. The issue MUST specify the link to the latest proposal in = the TC mailing list archives. _Note:_ the link MUST be in the issue descrip= tion itself - _not_ in the comments. +2. Reply by email to the comment email, requesting that the TC vote on re= solving the issue. The mail requesting the vote should include the followin= g, on a line by itself: =20 + `Fixes: https://github.com/oasis-tcs/virtio-spec/issues/NNN` (NNN is t= he issue number) +3. Please make sure to allow time for review between posting a comment an= d asking for a vote. + +#### TC standing rules + The TC adopted the following standing rule: -

- -Minor cleanups, including editorial formatting changes, spelling -and typo fixes can be committed directly into git for approval as -part of the next specification approval ballot. - -

    -
  1. To request such a commit, reply by email to the comment email, request= ing that the -issue is resolved under the minor cleanups standing rule. -
  2. -
  3. Please make sure to allow time for review between posting a comment -and asking for a commit.
  4. -
- -

Contact

-

Please send questions or comments about OASIS TC GitHub repositories to Robin Cover and C= het Ensign. For questions about content in this repository, please con= tact the TC Chair or Co-Chairs as listed on the the virtio TC's home page.

- + +_Minor cleanups, including editorial formatting changes, spelling and typo= fixes can be committed directly into git for approval as part of the next = specification approval ballot._ + +1. To request such a commit, reply by email to the comment email, request= ing that the issue is resolved under the minor cleanups standing rule. +2. Please make sure to allow time for review between posting a comment an= d asking for a commit. + +### Contact + +Please send questions or comments about [OASIS TC GitHub repositories](htt= ps://www.oasis-open.org/resources/tcadmin/github-repositories-for-oasis-tc-= members-chartered-work) to [Robin Cover](mailto:robin@oasis-open.org) and [= Chet Ensign](mailto:chet.ensign@oasis-open.org). For questions about conten= t in this repository, please contact the TC Chair or Co-Chairs as listed on= the the virtio TC's [home page](https://www.oasis-open.org/committees/virt= io/). --=20 2.20.1 This publicly archived list offers a means to provide input to the OASIS Virtual I/O Device (VIRTIO) TC. In order to verify user consent to the Feedback License terms and to minimize spam in the list archive, subscription is required before posting. Subscribe: virtio-comment-subscribe@lists.oasis-open.org Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org List help: virtio-comment-help@lists.oasis-open.org List archive: https://lists.oasis-open.org/archives/virtio-comment/ Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lis= ts Committee: https://www.oasis-open.org/committees/virtio/ Join OASIS: https://www.oasis-open.org/join/