tests.
ClosedPublic
Actions

Authored by • rodrigc on Nov 19 2015, 9:58 PM.

Details

Reviewers

ngie

Group Reviewers

tests

Commits

rS291089: Copy README into /usr/tests

Summary

I have fielded many questions from people who see /usr/tests
on their system but do not know how to run the tests.
Throw these people a breadcrumb by putting this information
at the top of the README file, and then install the README in
/usr/tests.

Test Plan

make install

Diff Detail

Repository

rS FreeBSD src repository - subversion

Lint

Lint Not Applicable

Unit

Tests Not Applicable

Event Timeline

• rodrigc updated this revision to Diff 10361.Nov 19 2015, 9:58 PM

• rodrigc retitled this revision from to Add quick steps for running kyua tests to README. Install the README in /usr/tests..

• rodrigc updated this object.

• rodrigc edited the test plan for this revision. (Show Details)

Herald added a subscriber: imp. · View Herald TranscriptNov 19 2015, 9:58 PM

• rodrigc added a project: tests.Nov 19 2015, 9:59 PM

• rodrigc added a reviewer: tests.

It seems like this should be installed to /usr/share/docs

No, I don't want this in `/usr/share/docs`. This is meant to be *newbie* friendly so people can just go in /usr/tests
and figure out what to do relatively quickly by looking at the README.
The way to figure this out right now is confusing enough as it is with info scattered all over the place in different man pages,
wikis, etc. The end result is that newbies can't figure out what to do, and keep asking me.

In D4224#89049, @rodrigc wrote:

No, I don't want this in `/usr/share/docs`. This is meant to be *newbie* friendly so people can just go in /usr/tests
and figure out what to do relatively quickly by looking at the README.
The way to figure this out right now is confusing enough as it is with info scattered all over the place in different man pages,
wikis, etc. The end result is that newbies can't figure out what to do, and keep asking me.

I understand where you're coming from. It just gets to be a bit of a chicken and egg problem, i.e. how will they know where to look for the README file if they don't know about /usr/tests?

They already see it, they just don't know what to do once they are there.

ngie accepted this revision.Nov 19 2015, 11:29 PM

ngie added a reviewer: ngie.

This revision is now accepted and ready to land.Nov 19 2015, 11:29 PM

jmmv added a subscriber: jmmv.Nov 20 2015, 2:05 AM

jmmv added inline comments.

tests/README
4 ↗	(On Diff #10361)	Two headings of the same level, one immediately after the other, look really ugly. Consider removing this one.
11 ↗	(On Diff #10361)	Why not just refer people to tests(7) and rely on the properly formatted manual page? These instructions are redundant and will need extra maintenance. If the manpage is unsuitable as it is, change it. Add a new section at the very top saying "Quickstart guide" or something like that. The same applies for all the text below. The documentation belongs in the tests(7) manual page. I think it's OK for a README to exist here and provide brief pointers to the page, but the real contents should be there. If the current page has navigation issues, that's a different story, but they can certainly be addressed.

• rodrigc added inline comments.Nov 20 2015, 3:16 AM

tests/README
11 ↗	(On Diff #10361)	README and tests(7) in their current form are way to wordy. In tests(7), I need to scroll through nearly 50 lines of text before there is one sentence describing how to run the tests. A lot of tests(7) reflects your personal opinions of when and how to run tests. Those kind of opinions belong on your personal blog not in the man page. The kind of newbies we want to run the tests are not going to have the patience to read through all this stuff. I'm not sure how open you are to having the content in these documents trimmed.