Bug 1456897 - Remove unclear / unneeded options from minor update documentation
Summary: Remove unclear / unneeded options from minor update documentation
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: Red Hat OpenStack
Classification: Red Hat
Component: documentation
Version: 10.0 (Newton)
Hardware: Unspecified
OS: Unspecified
unspecified
unspecified
Target Milestone: ---
: ---
Assignee: Dan Macpherson
QA Contact: RHOS Documentation Team
URL:
Whiteboard:
: 1414262 1454710 (view as bug list)
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2017-05-30 15:57 UTC by Andreas Karis
Modified: 2020-06-11 13:57 UTC (History)
8 users (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Environment:
Last Closed: 2017-05-31 16:39:34 UTC
Target Upstream Version:


Attachments (Terms of Use)

Description Andreas Karis 2017-05-30 15:57:38 UTC
Description of problem:
Remove unclear / unneeded options from documentation

https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/10/html/upgrading_red_hat_openstack_platform/sect-updating_the_environment

~~~
2.3. Updating the Overcloud Packages

The Overcloud relies on standard RPM methods to update the environment. This involves two steps:

    Updating the current plan using your original openstack overcloud deploy command and including the --update-plan-only option. For example:

    $ openstack overcloud deploy --update-plan-only \
      --templates  \
      -e /usr/share/openstack-tripleo-heat-templates/environments/network-isolation.yaml \
      -e /home/stack/templates/network-environment.yaml \
      -e /home/stack/templates/storage-environment.yaml \
      -e /home/stack/templates/rhel-registration/environment-rhel-registration.yaml \
      -e /usr/share/openstack-tripleo-heat-templates/environments/updates/update-from-vip.yaml \
      -e /home/stack/templates/param-updates.yaml
~~~

Specifically, I'm referring to these 2 options:
~~~
      -e /usr/share/openstack-tripleo-heat-templates/environments/updates/update-from-vip.yaml \
      -e /home/stack/templates/param-updates.yaml
~~~

Note that either these are important and need to be explained in the doc, or they should be removed because their presence in combination with their name (`update-from-vip.yaml`, `param-updates.yaml`) is very confusing.

Thanks,

Andreas

Comment 1 Dan Macpherson 2017-05-30 16:49:02 UTC
Hi Andreas,

I've changed the confusing environment files to use an optional in brackets. So the command is now:

$ openstack overcloud deploy --update-plan-only \
  --templates  \
  -e /usr/share/openstack-tripleo-heat-templates/environments/network-isolation.yaml \
  -e /home/stack/templates/network-environment.yaml \
  -e /home/stack/templates/storage-environment.yaml \
  -e /home/stack/templates/rhel-registration/environment-rhel-registration.yaml \
  [OTHER ENVIRONMENT FILES]

I've applied this patch to all previous versions.

Does that suit what you were after?

Comment 2 Andreas Karis 2017-05-30 17:03:52 UTC
Hi,

Yes, that should do it :-)

Thanks!

- Andreas

Comment 3 Dan Macpherson 2017-05-30 17:04:22 UTC
*** Bug 1414262 has been marked as a duplicate of this bug. ***

Comment 4 Dan Macpherson 2017-05-30 17:04:33 UTC
*** Bug 1454710 has been marked as a duplicate of this bug. ***

Comment 5 Dan Macpherson 2017-05-30 17:12:22 UTC
Also checking with Sofer as per duplicate BZs.

Sofer, here are the links to the previous versions:

OSP9: https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/9/html-single/upgrading_red_hat_openstack_platform/#sect-Updating_the_Overcloud

OSP8: https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/8/html-single/upgrading_red_hat_openstack_platform/#sect-Updating_the_Overcloud

How do these look to you? Any further changes required?

Comment 6 Sofer Athlan-Guyot 2017-05-31 13:06:29 UTC
Hi Dan,

the usual expected "man" way is more like [-e <environment_file>|...] but that's just me :)[1]

If It looks good to Andreas that's fine by me.

Thanks,

[1] https://linux.die.net/man/7/man-pages

Comment 7 Andreas Karis 2017-05-31 14:08:55 UTC
[-e <environment_file>|...]     looks good, actually :)

Comment 8 Dan Macpherson 2017-05-31 15:20:17 UTC
Made the switch to the manpage syntax for OSP8 to OSP11. Here's the OSP11 version:

https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/11/html-single/upgrading_red_hat_openstack_platform/#sect-Updating_the_Overcloud

How does it look now, Sofer?

Comment 9 Sofer Athlan-Guyot 2017-05-31 16:27:11 UTC
Hi Dan,

(In reply to Dan Macpherson from comment #8)
> Made the switch to the manpage syntax for OSP8 to OSP11. Here's the OSP11
> version:
> 
> https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/11/
> html-single/upgrading_red_hat_openstack_platform/#sect-Updating_the_Overcloud
> 
> How does it look now, Sofer?

gorgeous :)

Thanks.

Comment 10 Dan Macpherson 2017-05-31 16:39:34 UTC
(In reply to Sofer Athlan-Guyot from comment #9)
> Hi Dan,
> 
> (In reply to Dan Macpherson from comment #8)
> > Made the switch to the manpage syntax for OSP8 to OSP11. Here's the OSP11
> > version:
> > 
> > https://access.redhat.com/documentation/en-us/red_hat_openstack_platform/11/
> > html-single/upgrading_red_hat_openstack_platform/#sect-Updating_the_Overcloud
> > 
> > How does it look now, Sofer?
> 
> gorgeous :)

https://ci.memecdn.com/5475760.jpg

> 
> Thanks.

No prob. Thanks for highlighting this issue!


Note You need to log in before you can comment on or make changes to this bug.