Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.debian.maint.python > #15654 > unrolled thread

Re: Docu: Need help to understand section about package creation

Back to article view | Back to linux.debian.maint.python

Contents

  Re: Docu: Need help to understand section about package creation <c.buhtz@posteo.jp> - 2024-03-28 20:00 +0100
    Re: Docu: Need help to understand section about package creation weepingclown <weepingclown@disroot.org> - 2024-03-28 20:40 +0100
      Re: Re: Docu: Need help to understand section about package creation Boyuan Yang <byang@debian.org> - 2024-03-29 04:50 +0100
        Re: Docu: Need help to understand section about package creation Andreas Tille <andreas@an3as.eu> - 2024-03-29 07:50 +0100
          Re: Docu: Need help to understand section about package creation <c.buhtz@posteo.jp> - 2024-03-29 09:00 +0100
        Re: Docu: Need help to understand section about package creation <c.buhtz@posteo.jp> - 2024-03-29 09:00 +0100
        Re: Docu: Need help to understand section about package creation <c.buhtz@posteo.jp> - 2024-03-29 09:00 +0100
          Re: Docu: Need help to understand section about package creation Carsten Schoenert <c.schoenert@t-online.de> - 2024-03-29 10:00 +0100
            Re: Docu: Need help to understand section about package creation <c.buhtz@posteo.jp> - 2024-03-29 12:30 +0100
            Re: Docu: Need help to understand section about package creation Paul Boddie <paul@boddie.org.uk> - 2024-03-29 14:00 +0100
              Re: Docu: Need help to understand section about package creation Carsten Schoenert <c.schoenert@t-online.de> - 2024-03-29 14:50 +0100
                Re: Docu: Need help to understand section about package creation weepingclown <weepingclown@disroot.org> - 2024-03-29 16:40 +0100
                  Re: Docu: Need help to understand section about package creation <c.buhtz@posteo.jp> - 2024-03-29 17:30 +0100
                Re: Docu: Need help to understand section about package creation <c.buhtz@posteo.jp> - 2024-03-29 17:20 +0100

#15654 — Re: Docu: Need help to understand section about package creation

Hello again,

the problem persists.

I don't have the right information in the wiki. So I don't know how to
proceed with creating a package.

Can someone point me into the right direction please.

I have the repo on Salsa. But it is empty. And the commands
described in "Creating a new package" don't help me to fill it up.

Thanks in advance,
Christian Buhtz

On 2024-03-20 22:32 <c.buhtz@posteo.jp> wrote:
> Hello,
> 
> in order to improve the documentation I need to understand some parts.
> But I am stuck. I don't get it what the authors trying to explain.
> 
> It is about "Creating a new package" section:
> https://wiki.debian.org/Python/GitPackaging#Creating_a_new_package
> 
> The second paragraph points to dsc-file creation described here:
> https://wiki.debian.org/PackagingWithGit/GitDpm/Initialize
> 
> The third paragraph is a list of shell commands that do not work in my
> case. For example "uscan" don't work because it does not know what and
> where to download. Of course I understand that.
> 
> I assume I need a dsc file?
> 
> It seems that my understanding problem is the second paragraph and the
> dsc-page it is linking, too.
> 
> For example the first paragraph on the page
> "/PackagingWithGit/GitDpm/Initialize" is impossible to understand for
> newbies. What is it talking about? There is the term "git-dpm" 
> pointing to "/PackagingWithGit/GitDpm/" (now after I edit that page
> myself). But I am not sure what "git-dpm" is and how much of that big
> page I should work on to make that "uscan" command run.
> 
> Kind
> Christian

[toc] | [next] | [standalone]

#15655

[Multipart message — attachments visible in raw view] — view raw

Hello Christian,

Without knowing what exactly fails for you, it is quite difficult to point out anything. The steps documented in the wiki are supposed to be working.

That said, the current packaging go to tool for the DPT should be py2dsp, if what you are working on is a python package. `apt install pypi2deb` will give the py2dsp command and `py2dsp <package-name-in-pypi>` can give you a nifty initial template to start with. For more info you can try `py2dsp --help`. What I typically use when creating a new package is `py2dsp --profile dpt --distribution unstable --revision 1 --github <github-url> <pypi-package-name>`.

No other structured documentation on using py2dsp is available AFAIK, and I did struggle initially to understand how to use it. Creating a wiki page for that has been my plan since then, but couldn't get to it because of time constraints as well as fear of presenting the wrong info. Maybe I'll try to get to that soon enough.

Hope this helps.

Best,
Ananthu

On 28 March 2024 6:55:30 pm UTC, c.buhtz@posteo.jp wrote:
>Hello again,
>
>the problem persists.
>
>I don't have the right information in the wiki. So I don't know how to
>proceed with creating a package.
>
>Can someone point me into the right direction please.
>
>I have the repo on Salsa. But it is empty. And the commands
>described in "Creating a new package" don't help me to fill it up.
>
>Thanks in advance,
>Christian Buhtz
>
>On 2024-03-20 22:32 <c.buhtz@posteo.jp> wrote:
>> Hello,
>> 
>> in order to improve the documentation I need to understand some parts.
>> But I am stuck. I don't get it what the authors trying to explain.
>> 
>> It is about "Creating a new package" section:
>> https://wiki.debian.org/Python/GitPackaging#Creating_a_new_package
>> 
>> The second paragraph points to dsc-file creation described here:
>> https://wiki.debian.org/PackagingWithGit/GitDpm/Initialize
>> 
>> The third paragraph is a list of shell commands that do not work in my
>> case. For example "uscan" don't work because it does not know what and
>> where to download. Of course I understand that.
>> 
>> I assume I need a dsc file?
>> 
>> It seems that my understanding problem is the second paragraph and the
>> dsc-page it is linking, too.
>> 
>> For example the first paragraph on the page
>> "/PackagingWithGit/GitDpm/Initialize" is impossible to understand for
>> newbies. What is it talking about? There is the term "git-dpm" 
>> pointing to "/PackagingWithGit/GitDpm/" (now after I edit that page
>> myself). But I am not sure what "git-dpm" is and how much of that big
>> page I should work on to make that "uscan" command run.
>> 
>> Kind
>> Christian
>

[toc] | [prev] | [next] | [standalone]

#15657

[Multipart message — attachments visible in raw view] — view raw

Hi,

(I am off debian-python mailing list -- please CC me.
Also, I cannot include previous text in the threads because
I don't have them in my mailbox. Sorry!)

Reading https://lists.debian.org/debian-python/2024/03/msg00152.html
and https://lists.debian.org/debian-python/2024/03/msg00151.html ,
I can see that
https://wiki.debian.org/Python/GitPackaging#Creating_a_new_package is
indeed poorly written:

*) It still points to pages of GitDpm, which the Python team is not
using anymore.

*) It does not describe the procedure of packaging from scratch very
well. To be precise, it lacks info about packaging from a status where
both git repo and the .dsc source package are nonexistant. It doesn't
describe the "gbp import-orig" subcommand for packaging initialization,
which is suprising. The same issue applies to
https://wiki.debian.org/PackagingWithGit .

For newcomers, I believe they will get lost at the very first line on
https://wiki.debian.org/Python/GitPackaging#Creating_a_new_package ,
which is "uscan". No one knows why uscan can work with an empty
directory. The newcomer may not even know what uscan is (actually they
are supposed to know what uscan is in advance -- but explanation should
be added here anyway).

If you really want a readily-available better documentation, consider
reading the official documentation of git-buildpackage at
https://honk.sigxcpu.org/projects/git-buildpackage/manual-html/ .
After you understand that, merge the remaining useful information from
https://wiki.debian.org/Python/GitPackaging to get a thorough
understanding.

I don't have a good solution to Wiki pages yet since the article logic
needs some major editing.

Thanks,
Boyuan Yang

[toc] | [prev] | [next] | [standalone]

#15658

Hi,

Am Thu, Mar 28, 2024 at 11:45:36PM -0400 schrieb Boyuan Yang:
> 
> I don't have a good solution to Wiki pages yet since the article logic
> needs some major editing.

I can't provide any help for the Wiki page for DPMT.  In Debian Med we
provide some resources for newcomers:

  Mentoring of the Month:
    https://salsa.debian.org/med-team/community/MoM/-/wikis/Mentoring-of-the-Month-(MoM)

  Debian Med policy is more verbose about packaging details
    https://med-team.pages.debian.net/policy/


Perhaps a hint to my Live packaging workshop

    https://debconf23.debconf.org/talks/34-live-packaging-workshop/

might be helpful as well.  I did more of these[1] - unfortunately not
all recordings are available.

Kind regards
    Andreas.

[1] https://people.debian.org/~tille/talks/other_en.html

-- 
https://fam-tille.de

[toc] | [prev] | [next] | [standalone]

#15659

On 2024-03-29 07:48 Andreas Tille <andreas@an3as.eu> wrote:
> Perhaps a hint to my Live packaging workshop
> 
>     https://debconf23.debconf.org/talks/34-live-packaging-workshop/

Also not Python (but Go?) related but I will check it out.

[toc] | [prev] | [next] | [standalone]

#15660

Dear Boyuan Yang,

Thanks for your feedback.

> I can see that
> https://wiki.debian.org/Python/GitPackaging#Creating_a_new_package is
> indeed poorly written:
> 
> *) It still
> [...]

I agree to your list of aspects that need to be improved.
It seems you really understood the "workflow" of a newbie.

> For newcomers, I believe they will get lost at the very first line on
> https://wiki.debian.org/Python/GitPackaging#Creating_a_new_package

Exactly.

> If you really want a readily-available better documentation, consider
> reading the official documentation of git-buildpackage at
> https://honk.sigxcpu.org/projects/git-buildpackage/manual-html/ .
> After you understand that, merge the remaining useful information from
> https://wiki.debian.org/Python/GitPackaging to get a thorough
> understanding.

I am not willing to do this. With all respect to the DPT but I don't
write new documentation from scratch. I am not in the position. I can
improve existing documentation as I did in the past.

But this thread is about that I am on a point where I am lost in the
current documentation and someone else with more experience and
knowledge should take over and clear the path.

Thanks,
Christian Buhtz

[toc] | [prev] | [next] | [standalone]

#15661

Dear Metchtilde,

Thanks for the reply.

On 2024-03-29 08:28 Mechtilde <ooo@mechtilde.de> wrote:
> If some want to have more information you can read
> 
> https://ddp-team.pages.debian.net/dpb/BuildWithGBP.pdf in German

This document is not Python related. The section about Python is empty.
See section 15 at PDF page 65.

[toc] | [prev] | [next] | [standalone]

#15662

Am 29.03.24 um 08:51 schrieb c.buhtz@posteo.jp:
> This document is not Python related. The section about Python is empty.
> See section 15 at PDF page 65.

This isn't really needed yet, packaging Debian packages is technically 
always the same.
You seems to have a general problem to understand what is the basic 
workflow, what are the steps, what are the various files in the debian/ 
folders are for, what are the constraints and relationships of these 
files and how the low level tools work together. You need to work on 
this first before starting to dive into special handling for different 
languages done by the helper tools.

So Mechtilde pointed correctly to the

New Maintainer Guide:
https://www.debian.org/doc/manuals/maint-guide/

and to the
Developer Reference:
https://www.debian.org/doc/manuals/developers-reference/

Asking meta questions (It's not working, what do I wrong?) isn't 
helpful, ask specific questions and describe what you already did befor 
you encountered the problem.

Starting with Debian packaging isn't a easy thing and there is *not* the 
one way to do it right. And there are for sure hundreds of HowTos out 
there. You will need to try a few of them and chose in the end the 
workflow that fit's best for you.

git-buildpackage is one of the high level tools that can and should 
packaging tasks easier, to use it effective you will need to know what 
it is doing under the hood, means you need to be familiar with the low 
level tools that getting called by gbp.

-- 
Regards
Carsten

[toc] | [prev] | [next] | [standalone]

#15663

On 2024-03-29 09:52 Carsten Schoenert <c.schoenert@t-online.de> wrote:
> New Maintainer Guide:
> https://www.debian.org/doc/manuals/maint-guide/

That document itself points to a new rewritten "tutorial" in its first
paragraph.

<https://www.debian.org/doc/manuals/debmake-doc/index.en.html>

I suggest to remove one of them. There is to much redundant and
sometimes out dated "documentation".

[toc] | [prev] | [next] | [standalone]

#15664

On Friday, 29 March 2024 09:52:14 CET Carsten Schoenert wrote:
> 
> Starting with Debian packaging isn't a easy thing and there is *not* the
> one way to do it right. And there are for sure hundreds of HowTos out
> there. You will need to try a few of them and chose in the end the
> workflow that fit's best for you.

The problem with this advice is that for the Debian Python Team, there 
probably aren't many ways to "do it right". Instead, as I understand it, there 
will be very few ways that people tolerate, as recent discussion on this list 
has indicated.

> git-buildpackage is one of the high level tools that can and should
> packaging tasks easier, to use it effective you will need to know what
> it is doing under the hood, means you need to be familiar with the low
> level tools that getting called by gbp.

I packaged stuff for Debian about ten years ago or so and recently repackaged 
one tool, whose package is now parked in a state where it could conceivably be 
incorporated into Debian but is evidently not of interest to anyone here (or I 
need to promote it more, perhaps). I have also been packaging Moin 2.0 which 
is coincidentally relevant to these documentation discussion threads.

After following the advice on the Debian Wiki about suitable approaches for 
packaging Python libraries and applications, I ended up reading all about gbp 
and trying out the different suggestions in its documentation. Although quite 
helpful, this documentation does not give concrete advice about what would-be 
packagers should do, so it really does fall on context-specific advice to fill 
in those gaps.

In the end, I did my usual thing and distilled the documentation's prose down 
to a concise workflow to remind me of what I might need to do if I were to 
start packaging something else. In fact, I wrote the following for the Moin 
2.0 packages and then made use of it for the other package:

git branch -c master upstream
git checkout -b debian/master
<introduce debian directory here>
git add debian
git commit
<introduce upstream tag here, if you want to avoid hassle with Salsa>
git push origin <upstream tag>
gbp buildpackage --git-debian-branch=debian/master \
  --git-upstream-tag='upstream/%(version)s' --git-builder=sbuild

This saves me from having to re-read the gbp documentation or find the 
appropriate mention on the Debian Wiki of whatever the accepted approach might 
be. I also wrote summaries to maintaining patches since it seemed that gbp 
could be quite obstructive if not operated in precisely the right fashion, not 
entirely obvious from its documentation.

Obviously, this leaves a lot of stuff out, but it is a reminder and not a 
complete guide. Indeed, the issue of what the Debian directory might contain 
is almost an orthogonal topic to the mechanics of gbp. And then there are the 
social or collaborative aspects of the exercise as well, like setting up a 
Salsa account and project, filing an ITP, and so on.

Yes, such matters are covered in the more general documentation, at least if 
it was updated and no longer refers to Alioth or whatever. But in this context 
the advice will be quite specific and not vague suggestions that present more 
choices to be made rather than eliminating them.

In any case, I commend this effort to improve the documentation. In some ways, 
it really is quite a brave endeavour. I would have made edits to various pages 
myself, but I don't want to tread on any toes, and I don't really have much 
time to spend on this matter alongside numerous other commitments at the 
moment.

Paul

P.S. The argument made about needing to understand what happens "under the 
hood" is something of an indictment of the way technology is developed these 
days. A tool that is meant to simplify something should present its own 
coherent level of abstraction; deferring to lower-level mechanisms is 
something that the Git developers and community like to do, which is why the 
usability of Git is the subject of occasional jokes and somewhat more 
infrequent attempts to wrap it in more usable interfaces.

[toc] | [prev] | [next] | [standalone]

#15665

Hello Paul,

Am 29.03.24 um 13:49 schrieb Paul Boddie:
> On Friday, 29 March 2024 09:52:14 CET Carsten Schoenert wrote:
>>
>> Starting with Debian packaging isn't a easy thing and there is *not* the
>> one way to do it right. And there are for sure hundreds of HowTos out
>> there. You will need to try a few of them and chose in the end the
>> workflow that fit's best for you.
> 
> The problem with this advice is that for the Debian Python Team, there
> probably aren't many ways to "do it right". Instead, as I understand it, there
> will be very few ways that people tolerate, as recent discussion on this list
> has indicated.

the question in general was not about the right and correct way in the 
DPT, it was about starting from scratch. At least I don't know of a 
right way from scratch that is written down as policy, would also make 
no real sense to me.
Starting Debian packaging isn't easy, but it's going to be more 
complicated if you think there is only one way that's correct. In the 
end DAK needs some files, how you create them is on your own.
The DPT policy doesn't say you need to do packaging a very specif way, 
it stated that git-buildpackage is the tool for organizing the VCS data.

The DPT policy gives you the freedom to do your packaging preparation 
how ever you like, but it is expected you finally upload the data of 
your work into a git tree with a specific layout so others can take your 
work and reproduce a package by using gbp.

gbp is very flexible, so if you like to use sbuild in favor of pbuilder 
e.g. than you can simply do so.

BTW: I posted my way on how I created a new Python package for Debian in 
the German Debian forum extensively and in length last year while DC 
[1]. Because I also know were starters typically struggle with and I was 
in the need to introduce a new Python package as a dependency for 
another package.
I'm unsure if Christian did follow my steps by trying to reproduce the 
package I was working on. I'm thinking he didn't, if he did then I'm 
wondering where he is having problems to prepare his package. Until now 
there is no "I did this and this, ..., I failed."

The feedback on my mini HowTo was quite low. So I wont do such things again.

> In the end, I did my usual thing and distilled the documentation's prose down
> to a concise workflow to remind me of what I might need to do if I were to
> start packaging something else. In fact, I wrote the following for the Moin
> 2.0 packages and then made use of it for the other package:
> 
> git branch -c master upstream
> git checkout -b debian/master
> <introduce debian directory here>
> git add debian
> git commit
> <introduce upstream tag here, if you want to avoid hassle with Salsa>
> git push origin <upstream tag>
> gbp buildpackage --git-debian-branch=debian/master \
>    --git-upstream-tag='upstream/%(version)s' --git-builder=sbuild

gbp makes all these steps easier I think. Even if you want to do it 
completely manually. Basically I do this

mkdir new-package && cd new-package
git init
# create a file debian/gbp.conf if you want to have it more convenient
gbp import-orig [--verbose] --sign-tags --pristine-tar 
/path/to/tarball-version.tar.{gz,...,xz}
# add required files into debian/
gbp dch -aR
gbp buildpackage --git-ignore-new [--git-builder=what_ever_you_like]
# run lintian, squash issues, prepare autopkgtest, commit changes atomically
# create a patch queue if needed
gbp pq import [--ignore-new]
# work on patches, commit them
gbp qp export
git add debian/patches && git commit
# hack further, finalize the package, create the final changelog entry 
if needed
git commit debian/changlog
gbp buildpackage ...
# upload, wait for the DAK email
gbp tag --sig-tags
git remote add salsa ....
gbp push [salsa]

But we will find ten more possible ways to create a new package from 
scratch. :)

...
> P.S. The argument made about needing to understand what happens "under the
> hood" is something of an indictment of the way technology is developed these
> days. A tool that is meant to simplify something should present its own
> coherent level of abstraction; deferring to lower-level mechanisms is
> something that the Git developers and community like to do, which is why the
> usability of Git is the subject of occasional jokes and somewhat more
> infrequent attempts to wrap it in more usable interfaces.

A good tool is always helpful, and a good first time user experience is 
also important. But I've seen a lot of people and contributors that were 
completely lost once a errors message was coming up and they did not 
know what to do and were to look. A good developer or engineer is always 
able to help themselves. Means he need to know how things work or at 
least were to look next to solve problems.

[1] https://debianforum.de/forum/viewtopic.php?t=187764

-- 
Regards
Carsten

[toc] | [prev] | [next] | [standalone]

#15672

[Multipart message — attachments visible in raw view] — view raw

Hi,

As an addendum, there is also dedicated wiki pages[0] intended to be of help to newcomers. Not saying that solves everything mentioned before, but it does help quite a lot. As I understand it, the current problem we have is more about the wiki being less organized than there not being sufficient resources or them not being easily accessible to everyone.

[0] https://wiki.debian.org/Packaging/Learn

Best,
Ananthu

[toc] | [prev] | [next] | [standalone]

#15674

On 2024-03-29 15:34 weepingclown <weepingclown@disroot.org> wrote:
> As I understand it, the current
> problem we have is more about the wiki being less organized than
> there not being sufficient resources or them not being easily
> accessible to everyone.

Correct. The information is there. But the linkage between them is
often missing. But there is also some outdated or redundant information.

As a positive (but of course not perfect) example I can name the "Guide
for Debian Maintainers" [1] by Osamu Aoki. In its preface these
describe its own location related to all the other packaging
documentation existing. Some pages later it gives a short introduction
to some tools and how they belong together. He gives the "big picture".

[1] -- <https://www.debian.org/doc/manuals/debmake-doc>

[toc] | [prev] | [next] | [standalone]

#15673

On 2024-03-29 14:48 Carsten Schoenert <c.schoenert@t-online.de> wrote:
> BTW: I posted my way on how I created a new Python package for Debian
> in the German Debian forum extensively and in length last year while
> DC [1]. Because I also know were starters typically struggle with and
> I was in the need to introduce a new Python package as a dependency
> for another package.
> I'm unsure if Christian did follow my steps
> [...]
> [1] https://debianforum.de/forum/viewtopic.php?t=187764

I followed this steps these days. We discussed some details but the
discussion got stuck. I didn't received an answer of my last question
in that thread.

Kind
Christian Buhtz

[toc] | [prev] | [standalone]

Back to top | Article view | linux.debian.maint.python

csiph-web