On Thu, May 05, 2022 at 02:02:40AM +0100, Tom Smyth wrote: > Hello Marc, Folks > > regarding the READMEs in ports there is a wide variance in the writing > style, sections, verbosity of the READMEs,
There's a barebone one: ports/infrastructure/templates/README.template > > as far as I can tell there does not seem to be a Template README ( I > could be wrong > but I have searched ports briefly )and the READMEs across a sampling > of ports shows > a wide variety of approaches > > Do we want to standardise the Readmes with a template > perhaps with the following headings and advice about what the content > of each headings should be ? > > > 1) minimal / basic install > - get users started on the port useful for newer users and students > trying out a specific ports > 2) known Issues perhaps OpenBSD specific > - alert users to issues / features that dont work in the port > > 3) Performance Optimisation > > 4) security hardening / attack surface reduction steps > 4a) sample additional BasicPF config required to allow the port to function > 4b) doas configuration > 4c) logging configuration > 4c) chroot jail guidance ... (if not already supported) even if it > may be chroot glamping rather than a chroot jail... > > do we want the READMEs in mdoc(7) or just txt > > 5) Example configs > (for testing the port and for giving user configuration ideas ?) > > > Hope this helps > > > > > On Sun, 1 May 2022 at 20:44, Marc Espie <es...@nerim.net> wrote: > > > > You guys got to remember those are mostly written by developers. > > > > There's a bit of a chicken&egg problem: when you've been playing with > > software for a while, it's difficult to figure out what might be a problem > > for newcomers. > > > > That said READMEs files should reflect stuff that's a good idea to do if > > you're using that package PREFERABLY IN A VERY TERSE MANNER. > > > > If you are using packages YOU CAN HELP. > > > > Yeah. > > > > What do you think is hard to figure out and could use a mention in a > > pkg-readme ? > > > > Bear in mind that we're mostly talking OpenBSD specific related stuff. > > > > But personally, I don't mind a quickstart on "unfriendly" opensource > > that's hard to get to work without looking at their docs. > > > > THIS IS AN OPPORTUNITY PEOPLE!!! > > > > You are using OpenBSD and you thing it's difficult to contribute ? > > > > Maybe you can share your experiences about making things work and what was > > hard to figure out ? > > > > (Side note: pkg land is very tricky to automate. Some of what you're going > > to > > say I'm probably already aware of, but nevertheless this might give an idea > > about priorities on what to work on first) > > > > > -- > Kindest regards, > Tom Smyth. > -- Antoine
