[AutoQA] #326: Create user-facing documentation for depcheck

[fedora-badges]

#326: Create user-facing documentation for depcheck
---------------------------+------------------------------------------------
 Reporter:  tflink         |       Owner:       
     Type:  task           |      Status:  new  
 Priority:  major          |   Milestone:  0.5.0
Component:  documentation  |    Keywords:       
---------------------------+------------------------------------------------
 Create a wiki page for depcheck that contains the following:
  * Thorough description of the test
  * How to read and interpret results
  * How to interpret the log output and use it to find failures
  * Description of common failures
  * Links to useful resources
    * correct procedure descriptions (e.g. packaging guidelines, etc).
    * Other relevant information

{{{
 #!comment
 For some reason, I can't get a ticket query with single result to render,
 changed to static
 }}}

Related to #317 - Create user-facing documentation for upgradepath

[fedora-badges]

#326: Create user-facing documentation for depcheck
---------------------------+------------------------------------------------
 Reporter:  tflink         |        Owner:  tflink  
     Type:  task           |       Status:  assigned
 Priority:  major          |    Milestone:  0.5.0   
Component:  documentation  |   Resolution:          
 Keywords:                 |  
---------------------------+------------------------------------------------
Changes (by tflink):

* owner:  => tflink
  * status:  new => assigned

Comment:

I've written some initial documentation for Depcheck on the fedoraproject
 wiki:
 https://fedoraproject.org/wiki/AutoQA_tests/Depcheck

[fedora-badges]

#326: Create user-facing documentation for depcheck
---------------------------+------------------------------------------------
 Reporter:  tflink         |        Owner:  tflink  
     Type:  task           |       Status:  assigned
 Priority:  major          |    Milestone:  0.5.0   
Component:  documentation  |   Resolution:          
 Keywords:                 |  
---------------------------+------------------------------------------------
Comment (by jlaska):

Replying to [comment:1 tflink]:
> I've written some initial documentation for Depcheck on the

fedoraproject wiki:
> https://fedoraproject.org/wiki/AutoQA_tests/Depcheck

Looking good, thanks for taking this one Tim.  I made a few
 [https://fedoraproject.org/w/index.php?title=AutoQA_tests%2FDepcheck&acti...
 wiki/wording changes], please feel free to accept or reject.

In the section ''Fixing Failures'', it mentions adding or removing
 dependencies.  Would it make sense to include an example of each of those
 scenarios in the ''Understanding failures''?

Also, the suggested resolution ''Remove missing dependencies'' seems odd,
 but I might not be in the right mindset.  How do you remove something that
 is missing?  Should it read, ''Remove incorrect dependencies'' instead?

[fedora-badges]

#326: Create user-facing documentation for depcheck
---------------------------+------------------------------------------------
 Reporter:  tflink         |        Owner:  tflink  
     Type:  task           |       Status:  assigned
 Priority:  major          |    Milestone:  0.5.0   
Component:  documentation  |   Resolution:          
 Keywords:                 |  
---------------------------+------------------------------------------------
Comment (by tflink):
> Looking good, thanks for taking this one Tim.  I made a few

[https://fedoraproject.org/w/index.php?title=AutoQA_tests%2FDepcheck&acti...
 wiki/wording changes], please feel free to accept or reject.

Looks good to me, I didn't realize that some of those macros existed.
> In the section ''Fixing Failures'', it mentions adding or removing

dependencies.  Would it make sense to include an example of each of those
 scenarios in the ''Understanding failures''?

I think that the errors are going to look the same either way since the
 only thing we really detect is missing dependencies. Or are you suggesting
 that the fixes go into more detail and show fixing a failed depcheck run
 in both ways?
> Also, the suggested resolution ''Remove missing dependencies'' seems

odd, but I might not be in the right mindset.  How do you remove something
 that is missing?  Should it read, ''Remove incorrect dependencies''
 instead?

Yeah, it doesn't make a whole lot of sense to be removing something which
 is already missing. I changed the wording on that.

[fedora-badges]

#326: Create user-facing documentation for depcheck
---------------------------+------------------------------------------------
 Reporter:  tflink         |        Owner:  tflink  
     Type:  task           |       Status:  assigned
 Priority:  major          |    Milestone:  0.5.0   
Component:  documentation  |   Resolution:          
 Keywords:                 |  
---------------------------+------------------------------------------------
Comment (by jlaska):

Replying to [comment:3 tflink]:
> > In the section ''Fixing Failures'', it mentions adding or removing

dependencies.  Would it make sense to include an example of each of those
 scenarios in the ''Understanding failures''?
> I think that the errors are going to look the same either way since the

only thing we really detect is missing dependencies. Or are you suggesting
 that the fixes go into more detail and show fixing a failed depcheck run
 in both ways?

Yeah, a bit more detail might help, but this might be for my education.
 I'm hoping the recommendations we offer are actionable for maintainers.
 Perhaps they point to existing documents on packaging, or an SOP on
 resolving issues </overkill>.  Of course, I don't think we need to detail
 *every* possible combination, but maybe thinking about specific failures,
 and more clearly articulating what the maintainers did to resolve the
 issue would help?

This got me wondering if it would help to outline several more (unique)
 examples of depcheck test failures in the section ''Understanding
 failures''.  Then, for each failure listed, include a brief statement on
 the actual corrective action taken.  In the example given already, the
 corrective action was to include the ''sigar.i686'' package in the x86_64
 f14 repo?

Then, the section ''Fixing failures'' continues as is, with just recaping
 and summarizing recommended corrective action.

I'll be happy to do some mock-ups/drafts if you can point me towards
 unique depcheck failure logs.

[fedora-badges]

#326: Create user-facing documentation for depcheck
---------------------------+------------------------------------------------
 Reporter:  tflink         |        Owner:  tflink  
     Type:  task           |       Status:  assigned
 Priority:  major          |    Milestone:  0.5.0   
Component:  documentation  |   Resolution:          
 Keywords:                 |  
---------------------------+------------------------------------------------
Comment (by kparal):

I believe we will add more examples into that wiki page continuously as we
 work on different depcheck failures. The basic content is included. I
 think we can close this ticket, what do you think?

[fedora-badges]

#326: Create user-facing documentation for depcheck
---------------------------+------------------------------------------------
 Reporter:  tflink         |        Owner:  tflink
     Type:  task           |       Status:  closed
 Priority:  major          |    Milestone:  0.5.0 
Component:  documentation  |   Resolution:  fixed 
 Keywords:                 |  
---------------------------+------------------------------------------------
Changes (by tflink):

* status:  assigned => closed
  * resolution:  => fixed

Comment:

This will need more examples as we find them and may need more work in the
 future but I agree that this ticket can be closed for now.