[PATCH 0/4] docs cleanups
Cleanups based on review of series converting a bunch of docs to rST format. Peter Krempa (4): docs: securityprocess: Don't claim that we have maint branches docs: formatsnapshot: Move paragraphs describing 'disk' element together docs: formatsnapshot: Remove explicit listing of supported snapshot formats docs: formatsnapshot: Remove empty 'seclabel' definition docs/formatsnapshot.rst | 24 +++++++++++------------- docs/securityprocess.rst | 6 ++---- 2 files changed, 13 insertions(+), 17 deletions(-) -- 2.35.1
The 'Branch fixing policy' paragraph claims that we have at least one actively maintained stable branch which isn't currently the case. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/securityprocess.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/securityprocess.rst b/docs/securityprocess.rst index adddbf76b0..fe64e94f80 100644 --- a/docs/securityprocess.rst +++ b/docs/securityprocess.rst @@ -84,8 +84,6 @@ engineers on the security team. Branch fixing policy -------------------- -The libvirt community maintains one or more stable release branches at any given -point in time. The security team will aim to publish fixes for GIT master (which -will become the next major release) and each currently maintained stable release -branch. The distro maintainers will be responsible for backporting the +The security team will publish fixes for GIT master (which will become the next +major release). The distro maintainers will be responsible for backporting the officially published fixes to other release branches where applicable. -- 2.35.1
On 3/9/22 10:09, Peter Krempa wrote:
The 'Branch fixing policy' paragraph claims that we have at least one actively maintained stable branch which isn't currently the case.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/securityprocess.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-)
diff --git a/docs/securityprocess.rst b/docs/securityprocess.rst index adddbf76b0..fe64e94f80 100644 --- a/docs/securityprocess.rst +++ b/docs/securityprocess.rst @@ -84,8 +84,6 @@ engineers on the security team. Branch fixing policy --------------------
-The libvirt community maintains one or more stable release branches at any given -point in time. The security team will aim to publish fixes for GIT master (which -will become the next major release) and each currently maintained stable release -branch. The distro maintainers will be responsible for backporting the +The security team will publish fixes for GIT master (which will become the next +major release). The distro maintainers will be responsible for backporting the officially published fixes to other release branches where applicable.
Yeah, we don't really do that, but removing is looks too harsh. Maybe mention that we might create a maint branch? OTOH, a crasher we had wasn't serious enough for us to create a maint branch: https://listman.redhat.com/archives/libvir-list/2022-March/228906.html So in the end, off it goes. Michal
On Wed, Mar 09, 2022 at 10:47:45 +0100, Michal Prívozník wrote:
On 3/9/22 10:09, Peter Krempa wrote:
The 'Branch fixing policy' paragraph claims that we have at least one actively maintained stable branch which isn't currently the case.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/securityprocess.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-)
diff --git a/docs/securityprocess.rst b/docs/securityprocess.rst index adddbf76b0..fe64e94f80 100644 --- a/docs/securityprocess.rst +++ b/docs/securityprocess.rst @@ -84,8 +84,6 @@ engineers on the security team. Branch fixing policy --------------------
-The libvirt community maintains one or more stable release branches at any given -point in time. The security team will aim to publish fixes for GIT master (which -will become the next major release) and each currently maintained stable release -branch. The distro maintainers will be responsible for backporting the +The security team will publish fixes for GIT master (which will become the next +major release). The distro maintainers will be responsible for backporting the officially published fixes to other release branches where applicable.
Yeah, we don't really do that, but removing is looks too harsh. Maybe mention that we might create a maint branch? OTOH, a crasher we had wasn't serious enough for us to create a maint branch:
https://listman.redhat.com/archives/libvir-list/2022-March/228906.html
So in the end, off it goes.
In my previous posting of this patch (sorry forgot to mark it as v2) I attempted to use vague language to hint that there _might_ be a maint branch, but Jano pointed out that we didn't really do it for a very long time: https://listman.redhat.com/archives/libvir-list/2022-March/229067.html I can go with that version, but I agreed that it's unlikely to be maintaining those.
On 3/9/22 11:06, Peter Krempa wrote:
On Wed, Mar 09, 2022 at 10:47:45 +0100, Michal Prívozník wrote:
On 3/9/22 10:09, Peter Krempa wrote:
The 'Branch fixing policy' paragraph claims that we have at least one actively maintained stable branch which isn't currently the case.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/securityprocess.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-)
diff --git a/docs/securityprocess.rst b/docs/securityprocess.rst index adddbf76b0..fe64e94f80 100644 --- a/docs/securityprocess.rst +++ b/docs/securityprocess.rst @@ -84,8 +84,6 @@ engineers on the security team. Branch fixing policy --------------------
-The libvirt community maintains one or more stable release branches at any given -point in time. The security team will aim to publish fixes for GIT master (which -will become the next major release) and each currently maintained stable release -branch. The distro maintainers will be responsible for backporting the +The security team will publish fixes for GIT master (which will become the next +major release). The distro maintainers will be responsible for backporting the officially published fixes to other release branches where applicable.
Yeah, we don't really do that, but removing is looks too harsh. Maybe mention that we might create a maint branch? OTOH, a crasher we had wasn't serious enough for us to create a maint branch:
https://listman.redhat.com/archives/libvir-list/2022-March/228906.html
So in the end, off it goes.
In my previous posting of this patch (sorry forgot to mark it as v2) I attempted to use vague language to hint that there _might_ be a maint branch, but Jano pointed out that we didn't really do it for a very long time:
https://listman.redhat.com/archives/libvir-list/2022-March/229067.html
I can go with that version, but I agreed that it's unlikely to be maintaining those.
Oh, I did not realize this was v2 and in v1 you were told to remove this. As I said, in the end I am okay with your change. Michal
There was another paragraph describing the attribute 'type' of the 'disk' element under the description of the subelements. Move it to the top to get all relevant information in one place. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatsnapshot.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/formatsnapshot.rst b/docs/formatsnapshot.rst index 0ad397316c..b0d8d7ea2f 100644 --- a/docs/formatsnapshot.rst +++ b/docs/formatsnapshot.rst @@ -124,6 +124,17 @@ The top-level ``domainsnapshot`` element may contain the following elements: corresponding domain disk, while others like qemu allow this field to override the domain default. + :since:`Since 1.2.2` the ``disk`` element supports an optional attribute + ``type`` if the ``snapshot`` attribute is set to ``external``. This + attribute specifies the snapshot target storage type and allows to + overwrite the default ``file`` type. The ``type`` attribute along with + the format of the ``source`` sub-element is identical to the ``source`` + element used in domain disk definitions. See the `disk devices + <formatdomain.html#elementsDisks>`__ section documentation for further + information. Libvirt currently supports the ``type`` element in the qemu + driver and supported values are ``file``, ``block`` and ``network`` with + a protocol of ``gluster`` :since:`(since 1.2.2)` . + ``source`` If the snapshot mode is external (whether specified or inherited), @@ -151,17 +162,6 @@ The top-level ``domainsnapshot`` element may contain the following elements: ``seclabel`` - :since:`Since 1.2.2` the ``disk`` element supports an optional attribute - ``type`` if the ``snapshot`` attribute is set to ``external``. This - attribute specifies the snapshot target storage type and allows to - overwrite the default ``file`` type. The ``type`` attribute along with - the format of the ``source`` sub-element is identical to the ``source`` - element used in domain disk definitions. See the `disk devices - <formatdomain.html#elementsDisks>`__ section documentation for further - information. Libvirt currently supports the ``type`` element in the qemu - driver and supported values are ``file``, ``block`` and ``network`` with - a protocol of ``gluster`` :since:`(since 1.2.2)` . - ``creationTime`` A readonly representation of the time this snapshot was created. The time is -- 2.35.1
On 3/9/22 10:09, Peter Krempa wrote:
There was another paragraph describing the attribute 'type' of the 'disk' element under the description of the subelements. Move it to the top to get all relevant information in one place.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatsnapshot.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-)
diff --git a/docs/formatsnapshot.rst b/docs/formatsnapshot.rst index 0ad397316c..b0d8d7ea2f 100644 --- a/docs/formatsnapshot.rst +++ b/docs/formatsnapshot.rst @@ -124,6 +124,17 @@ The top-level ``domainsnapshot`` element may contain the following elements: corresponding domain disk, while others like qemu allow this field to override the domain default.
+ :since:`Since 1.2.2` the ``disk`` element supports an optional attribute + ``type`` if the ``snapshot`` attribute is set to ``external``. This + attribute specifies the snapshot target storage type and allows to + overwrite the default ``file`` type. The ``type`` attribute along with + the format of the ``source`` sub-element is identical to the ``source`` + element used in domain disk definitions. See the `disk devices + <formatdomain.html#elementsDisks>`__ section documentation for further + information. Libvirt currently supports the ``type`` element in the qemu + driver and supported values are ``file``, ``block`` and ``network`` with + a protocol of ``gluster`` :since:`(since 1.2.2)` . + ``source``
If the snapshot mode is external (whether specified or inherited), @@ -151,17 +162,6 @@ The top-level ``domainsnapshot`` element may contain the following elements:
``seclabel``
- :since:`Since 1.2.2` the ``disk`` element supports an optional attribute - ``type`` if the ``snapshot`` attribute is set to ``external``. This - attribute specifies the snapshot target storage type and allows to - overwrite the default ``file`` type. The ``type`` attribute along with - the format of the ``source`` sub-element is identical to the ``source`` - element used in domain disk definitions. See the `disk devices - <formatdomain.html#elementsDisks>`__ section documentation for further - information. Libvirt currently supports the ``type`` element in the qemu - driver and supported values are ``file``, ``block`` and ``network`` with - a protocol of ``gluster`` :since:`(since 1.2.2)` . - ``creationTime``
A readonly representation of the time this snapshot was created. The time is
This doesn't look right because it leaves ``seclabel'' hanging in the air with no content. Michal
In blockdev mode we support creating snapshots on all kinds of storage that qemu allows us to format the image. Drop the part of the sentence enumerating explicitly supported protocols. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatsnapshot.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/formatsnapshot.rst b/docs/formatsnapshot.rst index b0d8d7ea2f..e0f4c72235 100644 --- a/docs/formatsnapshot.rst +++ b/docs/formatsnapshot.rst @@ -132,8 +132,8 @@ The top-level ``domainsnapshot`` element may contain the following elements: element used in domain disk definitions. See the `disk devices <formatdomain.html#elementsDisks>`__ section documentation for further information. Libvirt currently supports the ``type`` element in the qemu - driver and supported values are ``file``, ``block`` and ``network`` with - a protocol of ``gluster`` :since:`(since 1.2.2)` . + driver and supported values are ``file``, ``block`` and ``network`` + :since:`(since 1.2.2)`. ``source`` -- 2.35.1
The security label setting for the external images is part of the 'source' element and documented there. Remove the empty definition added accidentally in commit ac88a8cfad1 Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatsnapshot.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/formatsnapshot.rst b/docs/formatsnapshot.rst index e0f4c72235..0fee35d89c 100644 --- a/docs/formatsnapshot.rst +++ b/docs/formatsnapshot.rst @@ -160,8 +160,6 @@ The top-level ``domainsnapshot`` element may contain the following elements: sub-element can be used with same semantics as the identically named subelement of the domain definition disk's driver. - ``seclabel`` - ``creationTime`` A readonly representation of the time this snapshot was created. The time is -- 2.35.1
On 3/9/22 10:09, Peter Krempa wrote:
The security label setting for the external images is part of the 'source' element and documented there. Remove the empty definition added accidentally in commit ac88a8cfad1
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatsnapshot.rst | 2 -- 1 file changed, 2 deletions(-)
diff --git a/docs/formatsnapshot.rst b/docs/formatsnapshot.rst index e0f4c72235..0fee35d89c 100644 --- a/docs/formatsnapshot.rst +++ b/docs/formatsnapshot.rst @@ -160,8 +160,6 @@ The top-level ``domainsnapshot`` element may contain the following elements: sub-element can be used with same semantics as the identically named subelement of the domain definition disk's driver.
- ``seclabel`` - ``creationTime``
A readonly representation of the time this snapshot was created. The time is
Ah, alright so my comment to 2/4 is not true completely. Maybe squash these two together? Or don't, I don't care that much. Michal
On Wed, Mar 09, 2022 at 10:48:55 +0100, Michal Prívozník wrote:
On 3/9/22 10:09, Peter Krempa wrote:
The security label setting for the external images is part of the 'source' element and documented there. Remove the empty definition added accidentally in commit ac88a8cfad1
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatsnapshot.rst | 2 -- 1 file changed, 2 deletions(-)
diff --git a/docs/formatsnapshot.rst b/docs/formatsnapshot.rst index e0f4c72235..0fee35d89c 100644 --- a/docs/formatsnapshot.rst +++ b/docs/formatsnapshot.rst @@ -160,8 +160,6 @@ The top-level ``domainsnapshot`` element may contain the following elements: sub-element can be used with same semantics as the identically named subelement of the domain definition disk's driver.
- ``seclabel`` - ``creationTime``
A readonly representation of the time this snapshot was created. The time is
Ah, alright so my comment to 2/4 is not true completely. Maybe squash these two together? Or don't, I don't care that much.
The problem is that the paragraph I moved in 2/4 didn't belong at all under the seclabel heading. I can reorder them, but other than that it's completely separate.
On 3/9/22 11:04, Peter Krempa wrote:
On Wed, Mar 09, 2022 at 10:48:55 +0100, Michal Prívozník wrote:
On 3/9/22 10:09, Peter Krempa wrote:
The security label setting for the external images is part of the 'source' element and documented there. Remove the empty definition added accidentally in commit ac88a8cfad1
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatsnapshot.rst | 2 -- 1 file changed, 2 deletions(-)
diff --git a/docs/formatsnapshot.rst b/docs/formatsnapshot.rst index e0f4c72235..0fee35d89c 100644 --- a/docs/formatsnapshot.rst +++ b/docs/formatsnapshot.rst @@ -160,8 +160,6 @@ The top-level ``domainsnapshot`` element may contain the following elements: sub-element can be used with same semantics as the identically named subelement of the domain definition disk's driver.
- ``seclabel`` - ``creationTime``
A readonly representation of the time this snapshot was created. The time is
Ah, alright so my comment to 2/4 is not true completely. Maybe squash these two together? Or don't, I don't care that much.
The problem is that the paragraph I moved in 2/4 didn't belong at all under the seclabel heading. I can reorder them, but other than that it's completely separate.
Nah, probably not worth the extra work. Merge these as they are. Michal
On a Wednesday in 2022, Peter Krempa wrote:
Cleanups based on review of series converting a bunch of docs to rST format.
Peter Krempa (4): docs: securityprocess: Don't claim that we have maint branches docs: formatsnapshot: Move paragraphs describing 'disk' element together docs: formatsnapshot: Remove explicit listing of supported snapshot formats docs: formatsnapshot: Remove empty 'seclabel' definition
docs/formatsnapshot.rst | 24 +++++++++++------------- docs/securityprocess.rst | 6 ++---- 2 files changed, 13 insertions(+), 17 deletions(-)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
participants (3)
-
Ján Tomko -
Michal Prívozník -
Peter Krempa