Re: Propositions to improve the documentation

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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 soooo 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@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to devel-leave@xxxxxxxxxxxxxxxxxxxxxxx
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@xxxxxxxxxxxxxxxxxxxxxxx
Do not reply to spam, report it: https://pagure.io/fedora-infrastructure/new_issue




[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Index of Archives]     [Fedora Announce]     [Fedora Users]     [Fedora Kernel]     [Fedora Testing]     [Fedora Formulas]     [Fedora PHP Devel]     [Kernel Development]     [Fedora Legacy]     [Fedora Maintainers]     [Fedora Desktop]     [PAM]     [Red Hat Development]     [Gimp]     [Yosemite News]

  Powered by Linux