Page MenuHomeFreeBSD

Mention atf(7) in tests(7)
ClosedPublic

Authored by trasz on May 1 2019, 1:01 PM.

Details

Summary

Mention atf(7) in tests(7).

Diff Detail

Repository
rS FreeBSD src repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

trasz created this revision.May 1 2019, 1:01 PM
trasz added a reviewer: ngie.May 1 2019, 1:02 PM
ngie added a comment.May 1 2019, 8:50 PM

I’m a bit ambivalent about this change, because it’s up on the wiki in greater detail: https://wiki.freebsd.org/TestingFreeBSD . kyua(1) references atf(7) IIRC, but it’s a level of indirection.

My point is, I’d personally prefer not mentioning just ATF in tests(7), but I want it to be enough of a living document where multiple sources can contribute to it, but mentioning the wiki page doesn’t seem like something that’s generally done from a manpage because the location and content in a wiki page can change.

ngie added a comment.May 1 2019, 9:48 PM
In D20124#433272, @ngie wrote:

I’m a bit ambivalent about this change, because it’s up on the wiki in greater detail: https://wiki.freebsd.org/TestingFreeBSD . kyua(1) references atf(7) IIRC, but it’s a level of indirection.
My point is, I’d personally prefer not mentioning just ATF in tests(7), but I want it to be enough of a living document where multiple sources can contribute to it, but mentioning the wiki page doesn’t seem like something that’s generally done from a manpage because the location and content in a wiki page can change.

Apologies. “Ambivalent” wasn’t the right word. I meant “torn”.

trasz added a comment.EditedMay 1 2019, 10:47 PM

The kyua(1) man page does reference atf... in a way - it just .Xrs to it, without mentioning it in the text itself. And yeah, the Wiki does include some more detail, but I always view it as kind of additional source - I know I went for the man page first, and simply pointing me in the right direction would spare me some work. Basically - 'man tests' is the first place I'd look for information on tests. And as it is now, it mentions how to run them, but not how to write them.

Also - the Wiki does mention ATF, but it also mentions Kyua, and that's not a reason to not mention Kyua in tests(7) :-)

emaste added a subscriber: emaste.May 20 2019, 8:13 PM

I like this.

ngie requested changes to this revision.May 20 2019, 8:55 PM
ngie added inline comments.
share/man/man7/tests.7
61 ↗(On Diff #56904)

Could this be rewritten as:

For information on how to write tests with ATF, see
.Xr atf 7 .

?

This revision now requires changes to proceed.May 20 2019, 8:55 PM
ngie added inline comments.May 20 2019, 8:56 PM
share/man/man7/tests.7
61 ↗(On Diff #56904)

Or maybe an unordered list here might be a good idea in the longterm with a list of all of the supported formats, but I think this is ok for now.

trasz added inline comments.May 21 2019, 8:30 AM
share/man/man7/tests.7
61 ↗(On Diff #56904)

I think I like my version better - if the reader heard about ATF, they don't need this sentence anyway.

This revision was not accepted when it landed; it landed in state Needs Revision.Jun 2 2019, 4:33 PM
This revision was automatically updated to reflect the committed changes.