Hello Marc, Folks regarding the READMEs in ports there is a wide variance in the writing style, sections, verbosity of the READMEs,
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.
