wishing minimal doc criteria for debian packages

[c***@posteo.jp]

I am not sure if this list is the right one for this discussion. Please
point me to the correct one.

I am new to the development environment in Debian. I sometimes ran into
inconvenience when I try to contribute to a package/project. And I
realize that "Debian" hasn't such high quality criteria as I thought.

A package should have this minimal informations
- link/info about the related upstream project (website)
- this should appear in the package source (e.g. README file) and in
the Debian package Tracker

This isn't much, isn't it? For some problems this is essential to
contribute to a package. E.g. I need upstream to check if a problem is
reported or fixed their. But sometimes this info is missing. And I
don't want to waste the maintainers time and ressources to ask such
simple questions: "Who is upstream?"

A nice to have (for me a must have) would be that upstream have to
provide a manpage. It should be up to the Debian staff to do the
documentation for upstream! There is enough other more important work
for Debian staff.

What do you think?

[c***@posteo.jp]

Does no one want to comment this?

Post by c***@posteo.jp
I am not sure if this list is the right one for this discussion.
Please point me to the correct one.
I am new to the development environment in Debian. I sometimes ran
into inconvenience when I try to contribute to a package/project. And
I realize that "Debian" hasn't such high quality criteria as I
thought.
A package should have this minimal informations
- link/info about the related upstream project (website)
- this should appear in the package source (e.g. README file) and in
the Debian package Tracker
This isn't much, isn't it? For some problems this is essential to
contribute to a package. E.g. I need upstream to check if a problem is
reported or fixed their. But sometimes this info is missing. And I
don't want to waste the maintainers time and ressources to ask such
simple questions: "Who is upstream?"
A nice to have (for me a must have) would be that upstream have to
provide a manpage. It should be up to the Debian staff to do the
documentation for upstream! There is enough other more important work
for Debian staff.
What do you think?

[Joost van Baal-Ilić]

Hi c.buhtz,

Thanks for your post on the list!

Post by c***@posteo.jp
Does no one want to comment this?

Post by c***@posteo.jp
I am not sure if this list is the right one for this discussion.
Please point me to the correct one.
I am new to the development environment in Debian. I sometimes ran
into inconvenience when I try to contribute to a package/project. And
I realize that "Debian" hasn't such high quality criteria as I
thought.
A package should have this minimal informations
- link/info about the related upstream project (website)

There is infrastructure in Debian packaging for this; the Homepage field.

Post by c***@posteo.jp

Post by c***@posteo.jp
- this should appear in the package source

It does.

Post by c***@posteo.jp

Post by c***@posteo.jp
(e.g. README file)

Rather not: that would no longer make it machine-parsable.

Post by c***@posteo.jp

Post by c***@posteo.jp
and in the Debian package Tracker

It does, see e.g. the "homepage" link at the right side of
https://tracker.debian.org/pkg/systraq .

Post by c***@posteo.jp

Post by c***@posteo.jp
This isn't much, isn't it? For some problems this is essential to
contribute to a package. E.g. I need upstream to check if a problem is
reported or fixed their. But sometimes this info is missing.

If you find a package which does not supply a Homepage field, please do
submit a bug for that package.

Post by c***@posteo.jp

Post by c***@posteo.jp
And I
don't want to waste the maintainers time and ressources to ask such
simple questions: "Who is upstream?"

Indeed, better to find out for yourself and stick that info in the bugreport.

Post by c***@posteo.jp

Post by c***@posteo.jp
A nice to have (for me a must have) would be that upstream have to
provide a manpage.

Yup, we agree. "Each program, utility, and function should have an associated
manual page included in the same package."
https://www.debian.org/doc/debian-policy/ch-docs.html#s12.1 . If a manpage is
lacking, please report that as a bug.

Post by c***@posteo.jp

Post by c***@posteo.jp
It should be up to the Debian staff to do the
documentation for upstream!

Did you forget a "not" here?

Post by c***@posteo.jp

Post by c***@posteo.jp
There is enough other more important work
for Debian staff.
What do you think?

One of the reasons I didn't reply earlier is the tone of your message. You
write "Debian should do this and that", while you didn't show you did some
research to find the answers to your questions yourself. That did not motivate
me.

Anyway, thanks for your post!

Bye,

Joost

[c***@posteo.jp]

Dear Joost,

I am sorry for the "tone". It wasn't against "Debian". It is only
because of Upstream. And I think this is a problem with my
none-native-english, too.

please do submit a bug for that package.

I did for all the points.

Post by c***@posteo.jp
A nice to have (for me a must have) would be that upstream have to
provide a manpage.

Yup, we agree. "Each program, utility, and function should have an
associated manual page included in the same package."
https://www.debian.org/doc/debian-policy/ch-docs.html#s12.1 . If a
manpage is lacking, please report that as a bug.

This doesn't point out who should provide the documentation. And that
is the point I want to bring up here. But of course I know this won't
change in the near feature. I just want to discuss about it and learn
from the Debian-oids. :)

e.g. The manpage of "libnotify" was written by debian-people. It is
debian-specific. In the upstream (gnome) source there is no manpage.
In my opinion, some people didn't checked very well while the
contribution process:
1. Someone contributed libnotify code to gnome. Someone accepted that
code but didn't take care about that there was no documentation.
2. Someone accepted libnotify as a debian package. She/he found out
that there is no manpage, wrote one and did work upstream should
have made.

to 1. I would never accept code without documentation in a project.
Here I don't have to explain how much workload undocumented code
produce while the lifetime of a software project. This is not about
saying "No" to the contributing person. It is about taking she/him by
her/his hand and explain and show how to provide well documented code.

to 2. It shouldn't not be up to debian to make the "dirty" work for
other projects. I am not sure how other devs think about that but for
me it would be kind of an accolade to see my own software accepted in
debian. I would treat "my" debian maintainer and her/his resources with
respect and write the documentation by myself. ;)

Post by c***@posteo.jp
It should be up to the Debian staff to do the
documentation for upstream!

Did you forget a "not" here?

Yes, of course. ;)

One of the reasons I didn't reply earlier is the tone of your
message. You write "Debian should do this and that",

This is about my English. ;)
IMO Debian is big and important enough that it could have an attitude
like: "We only accept your package if you document it."
It means Debian could set a quality standard for packages.

[Joost van Baal-Ilić]

Hi,

Post by c***@posteo.jp
I am sorry for the "tone". It wasn't against "Debian". It is only
because of Upstream. And I think this is a problem with my
none-native-english, too.

OK, I see.

Post by c***@posteo.jp

please do submit a bug for that package.

I did for all the points.

A, indeed,
https://bugs.debian.org/cgi-bin/pkgreport.cgi?dist=unstable;submitter=c.buhtz%40posteo.jp
shows quite a lot of them. Sorry for not checking earlier.

Post by c***@posteo.jp

Post by c***@posteo.jp
A nice to have (for me a must have) would be that upstream have to
provide a manpage.

Yup, we agree. "Each program, utility, and function should have an
associated manual page included in the same package."
https://www.debian.org/doc/debian-policy/ch-docs.html#s12.1 . If a
manpage is lacking, please report that as a bug.

This doesn't point out who should provide the documentation. And that
is the point I want to bring up here. But of course I know this won't
change in the near feature. I just want to discuss about it and learn
from the Debian-oids. :)
e.g. The manpage of "libnotify" was written by debian-people. It is
debian-specific. In the upstream (gnome) source there is no manpage.
In my opinion, some people didn't checked very well while the
1. Someone contributed libnotify code to gnome. Someone accepted that
code but didn't take care about that there was no documentation.
2. Someone accepted libnotify as a debian package. She/he found out
that there is no manpage, wrote one and did work upstream should
have made.
to 1. I would never accept code without documentation in a project.
Here I don't have to explain how much workload undocumented code
produce while the lifetime of a software project. This is not about
saying "No" to the contributing person. It is about taking she/him by
her/his hand and explain and show how to provide well documented code.
to 2. It shouldn't not be up to debian to make the "dirty" work for
other projects. I am not sure how other devs think about that but for
me it would be kind of an accolade to see my own software accepted in
debian. I would treat "my" debian maintainer and her/his resources with
respect and write the documentation by myself. ;)

Post by c***@posteo.jp
It should be up to the Debian staff to do the
documentation for upstream!

Did you forget a "not" here?

Yes, of course. ;)

One of the reasons I didn't reply earlier is the tone of your
message. You write "Debian should do this and that",

This is about my English. ;)
IMO Debian is big and important enough that it could have an attitude
like: "We only accept your package if you document it."
It means Debian could set a quality standard for packages.

So your point is that upstream could do better? But then why are you telling
this on a Debian list? I guess you should tell upstream, right?

You could e.g. report bugs in upstream bugtrackers and point to the Debian
manpage?

Bye,

Joost

[c***@posteo.jp]

Hi Joost

On 2017-08-04 17:16 Joost van Baal-Ilić

Post by Joost van Baal-Ilić
So your point is that upstream could do better? But then why are you
telling this on a Debian list? I guess you should tell upstream,
right?
You could e.g. report bugs in upstream bugtrackers and point to the
Debian manpage?

Of course I reported to upstream, too. They do there "patches are
welcome" mantra. But... You know my opinion here.

What Debians "job" could be here? Debian is big, important, powerful
and rule the world. :D Debian could lift up its finger make a diabolic
face and say to upstream: "Do your homework!" ;)

[Joost van Baal-Ilić]

Hi Christian,

Post by c***@posteo.jp
On 2017-08-04 17:16 Joost van Baal-Ilić

Post by Joost van Baal-Ilić
So your point is that upstream could do better? But then why are you
telling this on a Debian list? I guess you should tell upstream,
right?
You could e.g. report bugs in upstream bugtrackers and point to the
Debian manpage?

Of course I reported to upstream, too. They do there "patches are
welcome" mantra. But... You know my opinion here.

Well, imnsho this is exactly the point: if you want this situation to
improve, it is really effective to actually help doing the work by
e.g. supplying patches... :)

Tschüß!

Joost