Page MenuHomeFreeBSD

Add quick steps for running kyua tests to README. Install the README in /usr/tests.
ClosedPublic

Authored by rodrigc on Nov 19 2015, 9:58 PM.
Tags
Referenced Files
Unknown Object (File)
Jan 30 2024, 11:44 AM
Unknown Object (File)
Jan 14 2024, 12:10 AM
Unknown Object (File)
Dec 31 2023, 3:08 AM
Unknown Object (File)
Dec 24 2023, 9:17 AM
Unknown Object (File)
Dec 20 2023, 1:21 AM
Unknown Object (File)
Nov 29 2023, 5:31 PM
Unknown Object (File)
Nov 22 2023, 4:01 PM
Unknown Object (File)
Nov 22 2023, 1:16 PM
Subscribers

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 Passed
Unit
No Test Coverage
Build Status
Buildable 1225
Build 1229: arc lint + arc unit

Event Timeline

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)

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.

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 added a reviewer: ngie.
This revision is now accepted and ready to land.Nov 19 2015, 11:29 PM
jmmv added inline comments.
tests/README
4

Two headings of the same level, one immediately after the other, look really ugly. Consider removing this one.

11

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.

tests/README
11

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.

rodrigc added inline comments.
tests/README
4

OK

This revision was automatically updated to reflect the committed changes.
rodrigc marked an inline comment as done.