Re: Propositions to improve the documentation
https://youtu.be/VsnJymZRQOM is really excellent, thank you Miroslav On Wed, Oct 12, 2022 at 9:28 AM Miroslav Suchý wrote: > Dne 12. 10. 22 v 12:03 Sébastien Le Roux napsal(a): > > Dear All, > > I joined the packaging team recently, or should I say I joined the > mailing list, since for the rest I am > > still looking for a sponsor and all that ... anyway I want to share few > ideas with you ... > > In my first messages I highlighted that the documentation might need > some updates / improvements, > > for the newbie that I am parts of it were / are still confusing. > > Otto Liljalaasko offered me to suggest modifications in the doc ... here > I go ... again keep in mind > > that I am new to all this ;-) > > > > About " > https://docs.fedoraproject.org/en-US/package-maintainers/Using_the_Koji_Build_System/ > " > > You can even propose pull request. Just see the litle pencil (edit) button > in upper right corner. In this case it will > navigate you to > > > https://pagure.io/fedora-docs/package-maintainer-docs/blob/main/f/modules/ROOT/pages/Using_the_Koji_Build_System.adoc > > > > This doc, talks about "Koji" build, however the first command lines on > that page that introduces "Koji" > > referred to "fedpkg" and the relationship between both are somewhat > unclear, a diagram would really help. > > This can be definitely clearer. > > Koji builds from a dist-git. Fedpkg is tool which allows you to handle > dist-git and koji. Sometimes it provides > easy-to-remember wrapper around git and koji commands. > > > I could try to make one but again considering that I do not understand > thing properly I would likely mess it up. > > If I understand the doc properly the paragraph "Building with fedpkg > targets" should not be located > > at the beginning (that confused me really) but latter on introducing a > somewhat simpler, easier way > > *nod* it completely miss "how to work with dist-git" part. Feel free to > steal it from > https://www.youtube.com/watch?v=VsnJymZRQOM > > > About "https://docs.fedoraproject.org/en-US/packaging-guidelines/; > > > > I am still walking through this big doc, but my first comment is that it > does not point towards practical example(s), > It is guidelines. A set of policies and common standards. Not a teaching > book how to package SW. > > why not add a link to "https://src.fedoraproject.org/; (that was > pointed out to me by Alexander Ploumistos, thanks > > again) > > that would really help, to understand how things are done. > > Feel free to propose where to put the link. But it should come with a big > disclaimer, that sometimes packages in Fedora > (in src.f.o) do not follow and met Guidelines. There is various reasons. > From getting exception from FESCO to just being > old package and maintainer did not noticed a change in the guidelines > (because it change quite frequently). > > > Or maybe even better a basic, yet complete example, to build a RPM for > Fedora, some kind of a simple template to > > follow to do things properly. > > Beginning with the easiest, most simple example, yet complete, and the > rest of the doc would detail modifications that > > can > > Very very simple example > > https://xsuchy.github.io/rpm-spec-wizard/# > > More documentation, more teaching book than a guidelines. Still needs some > love: > > https://rpm-packaging-guide.github.io/ > > > With the actual format of the doc, and if you have no idea how to build > a spec file, well I simply think that you > > cannot do it, > > also because tt seems to me that several commands that are required for > a proper spec file to work are simply not > > introduced: > > > > -Group:, ex: Group: Productivity/Scientific/Physics > > Not even sure that this is required, but you can find it in many spec > file, if required this should be introduced, > > as well as the different groups available if Fedora. > > It is obsoleted for s long time, that it is not even mentioned in > documentation, that you should remove it. It will > make no harm to have it there, but it is not used at all. > > > > > -License:, ex License: AGPL-3.0-or-later (not even sure what keyword to > put here) > > Not even sure that this is required, but you can find it in many spec > file, if required this should be introduced, > > as well as the different keywoards to be used for packaging for Fedora. > > This is a must. Every package has to have this. It is document here: > > > https://docs.fedoraproject.org/en-US/packaging-guidelines/LicensingGuidelines/ > > > > > - %autosetup and %setup: in the doc %autosetup refers to %setup + patch, > %setup is not introduced, > > basically I know that it must be used but I have no idea what it does > ... what are the normal setup task ? > > *nod* > > The **only** documentation of %setup I am aware of is RPM Max > > http://ftp.rpm.org/max-rpm/s1-rpm-inside-macros.html > > This documentation is older than dinosaurs. But no one was able/brave to > rewrite it in up-to-date documentation. > > The
Re: Propositions to improve the documentation
Dne 12. 10. 22 v 12:03 Sébastien Le Roux napsal(a): Dear All, I joined the packaging team recently, or should I say I joined the mailing list, since for the rest I am still looking for a sponsor and all that ... anyway I want to share few ideas with you ... In my first messages I highlighted that the documentation might need some updates / improvements, for the newbie that I am parts of it were / are still confusing. Otto Liljalaasko offered me to suggest modifications in the doc ... here I go ... again keep in mind that I am new to all this ;-) About "https://docs.fedoraproject.org/en-US/package-maintainers/Using_the_Koji_Build_System/; You can even propose pull request. Just see the litle pencil (edit) button in upper right corner. In this case it will navigate you to https://pagure.io/fedora-docs/package-maintainer-docs/blob/main/f/modules/ROOT/pages/Using_the_Koji_Build_System.adoc This doc, talks about "Koji" build, however the first command lines on that page that introduces "Koji" referred to "fedpkg" and the relationship between both are somewhat unclear, a diagram would really help. This can be definitely clearer. Koji builds from a dist-git. Fedpkg is tool which allows you to handle dist-git and koji. Sometimes it provides easy-to-remember wrapper around git and koji commands. I could try to make one but again considering that I do not understand thing properly I would likely mess it up. If I understand the doc properly the paragraph "Building with fedpkg targets" should not be located at the beginning (that confused me really) but latter on introducing a somewhat simpler, easier way *nod* it completely miss "how to work with dist-git" part. Feel free to steal it from https://www.youtube.com/watch?v=VsnJymZRQOM About "https://docs.fedoraproject.org/en-US/packaging-guidelines/; I am still walking through this big doc, but my first comment is that it does not point towards practical example(s), It is guidelines. A set of policies and common standards. Not a teaching book how to package SW. why not add a link to "https://src.fedoraproject.org/; (that was pointed out to me by Alexander Ploumistos, thanks again) that would really help, to understand how things are done. Feel free to propose where to put the link. But it should come with a big disclaimer, that sometimes packages in Fedora (in src.f.o) do not follow and met Guidelines. There is various reasons. From getting exception from FESCO to just being old package and maintainer did not noticed a change in the guidelines (because it change quite frequently). Or maybe even better a basic, yet complete example, to build a RPM for Fedora, some kind of a simple template to follow to do things properly. Beginning with the easiest, most simple example, yet complete, and the rest of the doc would detail modifications that can Very very simple example https://xsuchy.github.io/rpm-spec-wizard/# More documentation, more teaching book than a guidelines. Still needs some love: https://rpm-packaging-guide.github.io/ With the actual format of the doc, and if you have no idea how to build a spec file, well I simply think that you cannot do it, also because tt seems to me that several commands that are required for a proper spec file to work are simply not introduced: -Group:, ex: Group: Productivity/Scientific/Physics Not even sure that this is required, but you can find it in many spec file, if required this should be introduced, as well as the different groups available if Fedora. It is obsoleted for s long time, that it is not even mentioned in documentation, that you should remove it. It will make no harm to have it there, but it is not used at all. -License:, ex License: AGPL-3.0-or-later (not even sure what keyword to put here) Not even sure that this is required, but you can find it in many spec file, if required this should be introduced, as well as the different keywoards to be used for packaging for Fedora. This is a must. Every package has to have this. It is document here: https://docs.fedoraproject.org/en-US/packaging-guidelines/LicensingGuidelines/ - %autosetup and %setup: in the doc %autosetup refers to %setup + patch, %setup is not introduced, basically I know that it must be used but I have no idea what it does ... what are the normal setup task ? *nod* The **only** documentation of %setup I am aware of is RPM Max http://ftp.rpm.org/max-rpm/s1-rpm-inside-macros.html This documentation is older than dinosaurs. But no one was able/brave to rewrite it in up-to-date documentation. The %autosetup is documented here: https://rpm-software-management.github.io/rpm/manual/autosetup.html Miroslav ___ devel mailing list -- devel@lists.fedoraproject.org To unsubscribe send an email to devel-le...@lists.fedoraproject.org Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines:
Re: Propositions to improve the documentation
On 10/12/22 13:03, Sébastien Le Roux wrote: Dear All, I joined the packaging team recently, or should I say I joined the mailing list, since for the rest I am still looking for a sponsor and all that ... anyway I want to share few ideas with you ... In my first messages I highlighted that the documentation might need some updates / improvements, for the newbie that I am parts of it were / are still confusing. There is some documentation scattered online. Quite a lot of discussion is on mailing lists also. Maybe the following tutorial will be helpful: https://jamezone.org/pleasure/software/Fedora/packager/ If anything else comes to mind while I study how to prepare and maintained RPMs I will let you know. That would be great. On another note, I want to thank you all for the warm welcome I received when I joined the list, this really was nice, I had a somewhat bad experience few years ago in an other open source community and was not sure what to expect here ... well the feeling is really nice, thank you ! Communicating with potentially everybody on the internet is tough. Conventions of welcoming behaviour differ quite considerably, but most of the time, intentions are good. Hope this helps. Best regards. Sébastien ___ devel mailing list -- devel@lists.fedoraproject.org To unsubscribe send an email to devel-le...@lists.fedoraproject.org Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org Do not reply to spam, report it: https://pagure.io/fedora-infrastructure/new_issue
