Re: READMEs files for ports
Antoine Merci ... I dont know How I missed that Thanks for pointing me in the direction . On Thu, 5 May 2022 at 09:24, Antoine Jacoutot wrote: > > 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 wrote: > > > > > > You guys got to remember those are mostly written by developers. > > > > > > There's a bit of a chicken 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 -- Kindest regards, Tom Smyth.
Re: READMEs files for ports
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 wrote: > > > > You guys got to remember those are mostly written by developers. > > > > There's a bit of a chicken 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
Re: READMEs files for ports
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 wrote: > > You guys got to remember those are mostly written by developers. > > There's a bit of a chicken 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.
Re: READMEs files for ports
On Mon, May 02, 2022 at 01:36:34PM +0200, Marc Espie wrote: > On Mon, May 02, 2022 at 01:28:38PM +0200, Solène Rapenne wrote: > > I don't think so because this is for your user and not for some user > > installed by the package. Here is the beginning of that section. > > > > > > The default limits set in login.conf(5) are not high enough to properly run > > GNOME. The default "datasize" must be bumped. There are several ways to do > > this: > > > > - bump the "default" class "datasize-cur" to 1024M (*not* recommended) > > - add users to the "staff" class (*not* recommended) > > - create a "gnome" login class and add users to it (recommended, see below) > > > > > > There is nothing that says that login.conf.d files have to be related to > a daemon in every case. > > Antoine, Robert, what do you think ? > > (there's still the issue of knowing how to add a user to a class, but > the gnome class could be added without any user interaction) Agreed, I will do this. -- Antoine
Re: READMEs files for ports
> - create a "gnome" login class and add users to it (recommended, see below) I think this a really sad approach. Suddenly a user who is in that group, has all the ridiculous limits for all their processes.
Re: READMEs files for ports
On Mon, May 02, 2022 at 01:28:38PM +0200, Solène Rapenne wrote: > I don't think so because this is for your user and not for some user > installed by the package. Here is the beginning of that section. > > > The default limits set in login.conf(5) are not high enough to properly run > GNOME. The default "datasize" must be bumped. There are several ways to do > this: > > - bump the "default" class "datasize-cur" to 1024M (*not* recommended) > - add users to the "staff" class (*not* recommended) > - create a "gnome" login class and add users to it (recommended, see below) > > There is nothing that says that login.conf.d files have to be related to a daemon in every case. Antoine, Robert, what do you think ? (there's still the issue of knowing how to add a user to a class, but the gnome class could be added without any user interaction)
Re: READMEs files for ports
Le 2022-05-02 13:14, Solène Rapenne a écrit : > Le Mon, 2 May 2022 14:08:23 +0300, > Mihai Popescu a écrit : > >> For gnome readme, there is this sequence: >> >> # cat <<'EOF' >>/etc/login.conf >> >> gnome:\ >> :datasize-cur=1024M:\ >> :tc=default: >> >> EOF >> >> It is a verbatim copy of what is displayed on the screen, Still I was >> not able to figure out what key to press or how to type to accomplish >> this :). I gave up and edited the file directly. >> >> Thanks. >> > > just for posterity the following text is a shell code > > cat <<'EOF' >>/etc/login.conf > > gnome:\ > :datasize-cur=1024M:\ > :tc=default: > > EOF > > > this tells cat to take input until it sees EOF and add the text to > /etc/login.conf file. Then we feed it the text we want to append, and > we tell it we finished by typing EOF. This is a command to type from a > shell. > > However, if it's not clear, maybe we should reword that part to tell > "add theses lines to /etc/login.conf" or something like that. Hi, Isn't it a case where it should go in /etc/login.conf.d/gnome now? I am genuinely asking, not proposing a change. Thanks.
Re: READMEs files for ports
On Mon, May 2, 2022 at 2:15 PM Solène Rapenne wrote: > > Le Mon, 2 May 2022 14:08:23 +0300, > Mihai Popescu a écrit : > > > For gnome readme, there is this sequence: > > > > # cat <<'EOF' >>/etc/login.conf > > > > gnome:\ > > :datasize-cur=1024M:\ > > :tc=default: > > > > EOF > > > > It is a verbatim copy of what is displayed on the screen, Still I was > > not able to figure out what key to press or how to type to accomplish > > this :). I gave up and edited the file directly. > > > > Thanks. > > > > just for posterity the following text is a shell code > > cat <<'EOF' >>/etc/login.conf > > gnome:\ > :datasize-cur=1024M:\ > :tc=default: > > EOF > > > this tells cat to take input until it sees EOF and add the text to > /etc/login.conf file. Then we feed it the text we want to append, and > we tell it we finished by typing EOF. This is a command to type from a > shell. > > However, if it's not clear, maybe we should reword that part to tell > "add theses lines to /etc/login.conf" or something like that. Well, I figure that out, but that is not my point. I tried to do that [TAB] spaces. I fact I typed the first line, the one with # cat ..., then [ENTER]. After that I got: > and [TAB] was not taken and put on the screen as a blank space. And about the "posterity" I am not so sure anymore, seeing what is happening to my eastern border :(. I surrender to Gnome 42 colors for now.
Re: READMEs files for ports
For gnome readme, there is this sequence: # cat <<'EOF' >>/etc/login.conf gnome:\ :datasize-cur=1024M:\ :tc=default: EOF It is a verbatim copy of what is displayed on the screen, Still I was not able to figure out what key to press or how to type to accomplish this :). I gave up and edited the file directly. Thanks.
Re: READMEs files for ports
On Sun, May 01, 2022 at 09:43:28PM +0200, Marc Espie wrote: > You guys got to remember those are mostly written by developers. > > There's a bit of a chicken 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) > dovecot readme says that "various" things need to be increased to make it work. No explanation how to do that. I have a page bookmarked that I have used in the past to be able to do those things in a new installation. I'm clueless about the right numbers. I just guess. postgresql-server seriously needs the defaults and the readme numbers changed. On a small server popping out 300 image file paths, I got terrible errors under mod_perl in the past. For many applications, the low numbers of connections are just fine. But any web server application needs far more. Some advice on what are good numbers for different situations would be a great help. I would love to help with those two, but I genuinely don't know the right answers beyond "I did this and it works". -- Chris Bennett
READMEs files for ports
You guys got to remember those are mostly written by developers. There's a bit of a chicken 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)
