Was looking to try out a new web server. The description indicated it (caddy) had what I was looking for. I built, and installed it. Now what do I do? IOW there is no / zero / any documentation what-so-ever. Do people really build, and run things without any thought as to how/what it does? OK maybe some do. But this is just plain wrong. It doesn't even come with a simple README. # man caddy No manual entry for caddy # cd /usr/ports/www/caddy; make deinstall Thank you for all your time, and consideration. --Chris
It's correct that it doesn't come with any manpage. It might be worth filing a bug upstream [1] for this. However, there is a README, README.md in the git repository [2] (which the port builds from) and there is documentation on the Homepage indicated in pgk-descr. I'm not quite sure what the intent of this PR is. The summary indicates some supsicion as to whether the port may be malicious. I haven't performed a full audit of the source code and don't know of one having taken place. Therefore, while it's theoretically possible there may be some malicious code involved, I haven't observed the port to do anything of the sort. I'm closing this PR as there isn't much I can do about this. Feel free to reopen if there is a manpage upstream to be included in the port or there are some concrete other concerns. [1] https://github.com/mholt/caddy/issues [2] https://github.com/mholt/caddy
(In reply to Fabian Freyer from comment #1) > It's correct that it doesn't come with any manpage. It might be worth filing > a bug upstream [1] for this. > > However, there is a README, README.md in the git repository [2] (which the > port builds from) and there is documentation on the Homepage indicated in > pgk-descr. This is of no value when attempting to use the port after installation. > > I'm not quite sure what the intent of this PR is. The summary indicates some > supsicion as to whether the port may be malicious. I haven't performed a > full audit of the source code and don't know of one having taken place. > Therefore, while it's theoretically possible there may be some malicious > code involved, I haven't observed the port to do anything of the sort. The purpose, and choice of title for this pr(1) is/was to indicate that an administrator auditing a system finding a command, or application with no documentation of any kind. Should, and Does find the file to be suspect. Highly suspect, should the system not be working correctly, and be suspected of infection. This is just another reason as to why UNIX has always provided some form of documentation for the (executable) files present on the system. Why should/would www/caddy think that they should be an exception to that rule? Why would/should www/caddy believe that documentation for it is of so little value, that it shouldn't accompany it's product? This is simply bad policy, and I don't think it's in FreeBSD', or it's users best interest to accommodate such a policy. Allowing www/caddy to continue with it's current policy sets a bad precedence, and should not be permitted. > > I'm closing this PR as there isn't much I can do about this. There is plenty you can do as a maintainer -- especially when you have given an indication that there is documentation online; you can simply add/include [at least] the Usage documentation. Does the README contain this? As such. I'm re-opening this pr(1). I hope you better understand now. :-) All the best. :-) --Chris > Feel free to > reopen if there is a manpage upstream to be included in the port or there > are some concrete other concerns. > > [1] https://github.com/mholt/caddy/issues > [2] https://github.com/mholt/caddy
It seems there is an issue [1] open for this upstream, my apologies for missing that earlier. I'll include the manpage once it exists upstream. I wasn't aware that software shipping any man pages or other documentation were out of scope for the ports tree, and that inclusion of such would be setting a dangerous precedent. On a quick, cursory, re-visitation of the Porter's Handbook [2], I didn't find any policies there - did I miss something, or is this some sort of unwritten rule? I agree that including documentation where possible is always beneficial. Where would you suggest installing the README.md[3] and/or how would you suggest referencing the online documentation[4]? [1] https://github.com/mholt/caddy/issues/1876 [2] https://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/ [3] https://github.com/mholt/caddy/blob/master/README.md [4] https://caddyserver.com/docs
Reporter has adequately described the issue. Documentation being provided is not a requirement, but providing a good post-installation experience is separately desirable. In the absence of packaged documentation (whether it doesn't exist, or isn't included in distribution files), a post-installation pkg-message should suffice in the meantime for minimal user messaging indicating 'where to go from here'. May I suggest pointing to: https://caddyserver.com/docs along with some basic messaging, depending on whats required from there, for example: - Create a foo.conf file in <path> (the port should provide one if one is necessary) - Add foo bar to cron for <this_feature> - Add foo_enable to /etc/rc.conf to enable caddy at boot I'd be happy to commit a patch including a pkg-message.
(In reply to Fabian Freyer from comment #3) > It seems there is an issue [1] open for this upstream, my apologies for > missing that earlier. I'll include the manpage once it exists upstream. > > I wasn't aware that software shipping any man pages or other documentation > were out of scope for the ports tree, and that inclusion of such would be > setting a dangerous precedent. On a quick, cursory, re-visitation of the > Porter's Handbook [2], I didn't find any policies there - did I miss > something, or is this some sort of unwritten rule? When I first began the attempt to become a maintainer, some 5yrs ago. I created a port that didn't have any docs (man, or otherwise). Not unlike your port; everything was online. I was informed that policy was such that this sort of thing was forbidden, for what should seem obvious reasons. The handbook wasn't as as grandiose back then, and since my mentor was a well seasoned, I didn't even look to question him. :-) So I guess it just seemed like TRTTD (the right thing to do). > > I agree that including documentation where possible is always beneficial. > Where would you suggest installing the README.md[3] /usr/local/share/docs/caddy The README should suffice if it provides usage instructions, and a link to the online documentation IMHO it should provide an apology for not adding it to their distribution -- they should apologize, not you. :-) > and/or how would you > suggest referencing the online documentation[4]? IMHO it should really be contained in the README. But if not, adding a message.in that ehoes "the full documentation for caddy can be found online at: http://wherever-the-caddy-docs-are-inline/ See also /usr/local/share/docs/caddy/README for basic usage instructions" > > [1] https://github.com/mholt/caddy/issues/1876 > [2] https://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/ > [3] https://github.com/mholt/caddy/blob/master/README.md > [4] https://caddyserver.com/docs All the best. --Chris
I tried to address this in review D14475. Please let me know here or in on review D14475 whether I can make the pkg-message clearer in any way.
ports r462653 adds a pkg-message that references the online documentation
Assign to committer that resolved
r462653 introduced pkg-message with description of what to do. Please feel free to create another bug report if you find pkg-message insufficient. *** This bug has been marked as a duplicate of bug 226131 ***
@Fabian Just wanted to chime in again, to thank you for doing this, Fabian. Nice job BTW. :-) --Chris