[CentOS-devel] Documentation help requested (Re: Upgrading from 6 to 7)

Mon Aug 6 15:55:41 UTC 2018
Rich Bowen <rbowen at redhat.com>


On 08/06/2018 11:44 AM, Trevor Hemsley wrote:
> On 06/08/18 16:39, Rich Bowen wrote:
>> Hi, folks,
>>
>> I was hoping that someone with more knowledge than I about the 6 -> 7 
>> upgrade process would have a look at 
>> https://wiki.centos.org/TipsAndTricks/CentOSUpgradeTool
>>
>> The page starts with a vague warning, and then continues to give 
>> detailed instructions, leaving it very unclear which parts the warning 
>> refers to.
> 
> It's not particularly vague.
> 
> [attachment:ArtWork/WikiDesign/icon-admonition-idea.png]
> 
> 	
> 
> *DO NOT USE this tool. Warning: use of this tool is currently BROKEN as 
> several system-critical packages are of a higher version number in 
> CentOS 6.7 than they are in CentOS 7 so those do not get upgraded 
> correctly. This renders yum and several other system tools non-functional.*
> 
> 
> How much more definite about it being broken and unusable does it need 
> to be?

You're correct - "vague" was the wrong word here. What's confusing is 
that this comment is then followed by HUNDREDS of words of 
documentation. We've all spent years with users who, faced by a doc like 
this, will gloss over the warning and move right on to the instructions, 
because the two things contradict each other, and they're just trying to 
solve a problem.

> 
>> If the process is broken, let's remove all of this and point to the 
>> correct process. If only a part of the process is broken, we need to 
>> remove that from the doc, and drop the scary warning.
> 
> It's broken and despite many calls for people to step up to maintain the 
> tool, nothing has happened.

ok, I'll replace the entire page with "This tool is no longer 
maintained" and leave it at that, unless anyone objects.

Leaving detailed incorrect instructions "for historical purposes" never 
ends well.

Thanks for the input.

-- 
Rich Bowen - rbowen at redhat.com
@CentOSProject // @rbowen
859 351 9166