Re: Uscan: watch and changelog

[c.buhtz]

Dear Paul,

thanks for your feedback.

On 2024-03-31 17:17 Paul Boddie  wrote:
> then the developers claim that they didn't have time to document

That is the advantage when doing FOSS. You do have the time. There is
not boss or customer behind your back. Teh problem in FOSS is just the
priorities of the developers and their management of time and
resources.

> Did you find my previous message about
> uscan helpful?

Yes, I did.

> > The situation is not healthy to me. So I need to stop from here with
> > fixing other peoples documentation.
> 
> I think that you can make a difference, so don't stop trying to do
> something about it.

One important skill of a FOSS developer/contributor is to know when to
stop and saying "no".

Anyway, I also think I won't make a difference when the whole system
(Debian) is against me. There is much more to do then just updating
wiki pages. I do respect the docracy but there are limits. And that is
where the project management should be somehow involved.

Re: Uscan: watch and changelog

[Paul Boddie]

On Sunday, 31 March 2024 15:31:36 CEST c.bu...@posteo.jp wrote:
> 
> Don't write and explain such things in emails. Save your time and
> resources. Write it into the wiki just one time and then you can link
> to it. You wrote it. I won't copy and paste your stuff. Ladies and
> Gentlemen please do edit your own wiki pages yourself. You are the
> experts here. I am not.

I agree broadly with these sentiments.

> This attitude is also one of the reasons why the wiki is in such a bad
> shape.

I somewhat agree with this, although it is actually why documentation is in 
such bad shape across the entire industry, not just the Debian Wiki. However, 
I sympathise with developers that there are only so many hours in the day, 
too, and that they are often tasked with getting working code out of the door, 
condemning supposedly optional activities like testing and documentation to 
perennial neglect.

I sympathise less with the school of development where everything is thrown 
over the side, redone with little benefit to everyone, and then the developers 
claim that they didn't have time to document anything, not least because they 
are about to go through the same performance all over again.

> Otherwise just delete the whole wiki. That would be an increase in
> the quality of Debians documentation. In its current state it is
> embarrassing and it harms the project called Debian.

I don't agree and I am evidently not the only one. There have been situations 
where the only usable documentation I could find was in the Debian Wiki.

> Debian is not a hobby. Doing FOSS shouldn't be an excuse for not taking
> responsibility.

Well, it should be more than a hobby, and it is indeed a job for some people. 
To upgrade it from hobby to job involves money, and that would definitely be 
an incentive for people to "take responsibility". Otherwise, nobody should 
believe that they can set people's work priorities: that is the job of the 
boss in an actual employment relationship.

> I tried. But it seems I am the only person caring for new contributors
> and how the read documentation. I am tortured with man pages and links
> to out dated documentation (e.g. "New maintainers guide").

I certainly care about it. Did you find my previous message about uscan 
helpful? I don't maintain any of these tools, but I am willing to share my 
experiences in order to evolve a reasonable consensus about how these tools 
might be used, eventually providing concise, usable documentation that would 
help newcomers quickly become productive.

> The situation is not healthy to me. So I need to stop from here with
> fixing other peoples documentation.

I think that you can make a difference, so don't stop trying to do something 
about it.

Paul

Re: Uscan: watch and changelog

[Michael Stehmann]

Hello.

Am 31.03.24 um 15:31 schrieb c.bu...@posteo.jp:


Otherwise just delete the whole wiki. That would be an increase in
the quality of Debians documentation. In its current state it is
embarrassing and it harms the project called Debian.


Do you really think, deleting for example this pages

https://wiki.debian.org/Teams
https://wiki.debian.org/Teams/PythonTeam

would be an improvement in documentation?

The quality of Debian documantion is improvable; but the Debian project 
is a do-ocracy [0]


Kind regards
Michael

[0] https://de.wikipedia.org/w/index.php?title=Do-ocracy=206673492 
(sorry, there is no english version)

Re: Uscan: watch and changelog

[c.buhtz]

Dear Soren,

my primary intention is always to improve Debian. That also involves a
better image to the public and potential new users and contributors.

On 2024-03-29 13:42 Soren Stoutner  wrote:
> Much of Debian’s documentation is not written for people
> who are new to the topic, but for people who already know the
> information and just want to be reminded about some of the tricky
> parts.

That kind of "documentation" is called a "reference". You point to one
of the problems of the Debian Wiki and other Debian documents. They are
often not focused enough to one purpose and/or target group. It is
often not clear to readers what the purpose and target group of a
specific wiki page or document is. And especially in a Wiki there are
too many authors not following any design rules except their own way of
thinking. Sometimes to much freedom is not healthy. A "head of docu"
person or institution watching the quality is missing in Debian.

I am aware of . But it seems they
don't have the power in Debian to establish rules about documentation
quality. And even there own wiki team page has much potential for
improvement.

> Anything you can do to improve the documentation would be greatly
> appreciated.

No, no, no! Sorry. I tried to give a polite hint in my previous mail
but it seems it did not reach you.

Don't write and explain such things in emails. Save your time and
resources. Write it into the wiki just one time and then you can link
to it. You wrote it. I won't copy and paste your stuff. Ladies and
Gentlemen please do edit your own wiki pages yourself. You are the
experts here. I am not.

This attitude is also one of the reasons why the wiki is in such a bad
shape.

Otherwise just delete the whole wiki. That would be an increase in
the quality of Debians documentation. In its current state it is
embarrassing and it harms the project called Debian.

Debian is not a hobby. Doing FOSS shouldn't be an excuse for not taking
responsibility.

I tried. But it seems I am the only person caring for new contributors
and how the read documentation. I am tortured with man pages and links
to out dated documentation (e.g. "New maintainers guide").

The situation is not healthy to me. So I need to stop from here with
fixing other peoples documentation.

Best,
Christian Buhtz

Re: Uscan: watch and changelog

[Soren Stoutner]

I agree.  Much of Debian’s documentation is not written for people who are new 
to the topic, but for people who already know the information and just want to 
be reminded about some of the tricky parts.

Anything you can do to improve the documentation would be greatly appreciated.

On Friday, March 29, 2024 1:12:12 PM MST c.bu...@posteo.jp wrote:
> On 2024-03-29 11:29 Soren Stoutner  wrote:
> > One of the interesting things about uscan
> 
> This is that kind of "big picture" explanations that should be written
> to the Wiki. Texts like this are the missing link between man pages,
> references and policy documents.
> 
> Thanks in advance


-- 
Soren Stoutner
so...@debian.org

signature.asc
Description: This is a digitally signed message part.

Re: Uscan: watch and changelog

[c.buhtz]

On 2024-03-29 11:29 Soren Stoutner  wrote:
> One of the interesting things about uscan

This is that kind of "big picture" explanations that should be written
to the Wiki. Texts like this are the missing link between man pages,
references and policy documents.

Thanks in advance

Re: Uscan: watch and changelog

[Soren Stoutner]

On Friday, March 29, 2024 10:16:56 AM MST c.bu...@posteo.jp wrote:
> There is no "opts=". So again. Why would you suggest to use "opts="? I want 
to
> learn. I don't want to fight.

One of the interesting things about uscan is there are often multiple different 
ways to connect to an upstream source and get what you want out of it.

So, for example, if upstream posts tarballs, you can scan the HTML for those 
and find one that matches the latest version number in the changelog (or one 
with a newer version number, which uscan can use to notify you an update is 
available).

However, uscan also speaks git.  If you use `opts=git`, then instead of 
scanning the HTML looking for a tarball, it connects through git and looks at 
the tags to find a suitable release.  It then clones that commit and uses the 
source to produce a tarball.

Some upstream repositories both produce release tarballs and tag their 
releases in git, so either approach would work.  Some only do one or the 
other.

-- 
Soren Stoutner
so...@debian.org

signature.asc
Description: This is a digitally signed message part.

Re: Uscan: watch and changelog

[Paul Boddie]

On Friday, 29 March 2024 17:39:04 CET c.bu...@posteo.jp wrote:
> 
> On 2024-03-29 16:23 Carsten Schoenert  wrote:
> > You need to use "opts=mode=git, ...", see the man page of uscan.
> 
> Are you sure. For example this watch file do not use "opts="
> https://sources.debian.org/src/backintime/1.4.3-1/debian/watch/

If I look at your releases page, I see that you have one release that you will 
probably be wanting to package:

https://codeberg.org/buhtz/hyperorg/releases

However, uscan seems to be driven by the debian/changelog and debian/watch 
files, with the former supplying the version or release to be searched for, 
and the latter specifying the mechanism by which the searching will occur.

So, I imagine that your debian/changelog would need an entry starting with 
something like this:

hyperorg (0.1.0-1) unstable; urgency=low

If you hadn't tagged a release in the repository, then you would probably have 
to invent a suitable version number based on the changeset identifier. 
Something like this perhaps:

hyperorg (0.1.0+git20240329.4a77811214-1) unstable; urgency=low

Here, I've used the changeset identifier of 4a77811214 which is the latest 
commit that I can see, and that hopefully serves to illustrate the principle.

I suppose that the watch file would then need to use the "mode=git" option.

[...]

> > And uscan will find the most recent version matching the regexp.
> 
> I see 3 different regex patterns in this line. Why?

I must admit to just copying the recommended patterns for my packaging 
exercises, largely because although I can happily explore the process of 
downloading a Web page - in your case, the one mentioned above - and parsing 
the HTML to get at the download links, I assume that someone has already done 
that hard work.

But to answer your question, what is happening is that the release or version 
from the changelog is transformed into something that might appear on the 
downloaded page. You need to get from "hyperorg-0.1.0-1" to this:

https://codeberg.org/buhtz/hyperorg/archive/v0.1.0.tar.gz

Or if a specific changeset is involved, the process is a bit more complicated, 
but would involve transforming "hyperorg-0.1.0+git20240329.4a77811214-1" into 
this:

https://codeberg.org/buhtz/hyperorg/archive/
4a77811214e5bd73247a197dbb5d1a4367c99109.tar.gz

To summarise, uscan is just searching a page listing releases or, in the 
second case, a specific Web page for an appropriate download that it can then 
obtain.

Hope this helps a little!

Paul

Re: Uscan: watch and changelog

[c.buhtz]

On 2024-03-29 18:07 Carsten Schoenert  wrote:
> Am 29.03.24 um 17:39 schrieb c.bu...@posteo.jp:
> > On 2024-03-29 16:23 Carsten Schoenert 
> > wrote:
> >> You need to use "opts=mode=git, ...", see the man page of uscan.
> > 
> > Are you sure.
> 
> Of course I'm sure, I've tested the snippets before posting it on the 
> list. Did you test this on your side and have any issues?

Again I was not clear. You wrote "need". So it is mandatory?
Then I gave you an example where "opts=" is not used. So it seems not
to be mandatory in all cases.

> > For example this watch file do not use "opts="
> > https://sources.debian.org/src/backintime/1.4.3-1/debian/watch/
> 
> You need to ask the person that did probably this creation or 
> modification. I can't answering this.

This line seems to work:

https://codeberg.org/buhtz/hyperorg/tags .*\/v(\d+).(\d+).(\d+).tar.gz

There is no "opts=". So again. Why would you suggest to use "opts="? I want to 
learn. I don't want to fight.

Re: Uscan: watch and changelog

[Carsten Schoenert]

Am 29.03.24 um 17:39 schrieb c.bu...@posteo.jp:

Dear Carsten,

thank for your reply and your patience with me. :)

On 2024-03-29 16:23 Carsten Schoenert  wrote:

You need to use "opts=mode=git, ...", see the man page of uscan.


Are you sure.


Of course I'm sure, I've tested the snippets before posting it on the 
list. Did you test this on your side and have any issues?



For example this watch file do not use "opts="
https://sources.debian.org/src/backintime/1.4.3-1/debian/watch/


You need to ask the person that did probably this creation or 
modification. I can't answering this.



Also some examples on the wikipage about "debian/watch" do not use
"opts=".


You seems to expect that the wiki is all known and answering place. No, 
that is this not. It's by nature always "outdated". But it's a wiki, 
everyone can edit it.



Please be aware that I don't only want to solve one technical problem
with one specific package. I want to understand the whole thing ("big
picture") to improve the documentation.


Well, that's not that complicated for uscan, it does mainly one thing 
(which is done in multiple steps, have a look into the man page), it's 
scanning upstream resources, fetching data and creates an tarball ready 
for importing.



opts="mode=git, \
   
uversionmangle=s/(\d)[_\.\-\+]?((RC|rc|pre|dev|beta|alpha)\.?\d*)$/$1~$2/,
\ dversionmangle=s/\+ds(\.?\d+)?$//" \
https://codeberg.org/buhtz/hyperorg.git \
   refs/tags/v(\d+\S+)


And uscan will find the most recent version matching the regexp.


I see 3 different regex patterns in this line. Why?


I see one that is relevant to your original question. The other two you 
mean are used in other "opts" variables, these variable are also 
explained too in the man page of uscan.


--
Regards
Carsten

Re: Uscan: watch and changelog

[c.buhtz]

Dear Carsten,

thank for your reply and your patience with me. :)

On 2024-03-29 16:23 Carsten Schoenert  wrote:
> You need to use "opts=mode=git, ...", see the man page of uscan.

Are you sure. For example this watch file do not use "opts="
https://sources.debian.org/src/backintime/1.4.3-1/debian/watch/

Also some examples on the wikipage about "debian/watch" do not use
"opts=".

Please be aware that I don't only want to solve one technical problem
with one specific package. I want to understand the whole thing ("big
picture") to improve the documentation.


> > opts="mode=git, \
> >   
> > uversionmangle=s/(\d)[_\.\-\+]?((RC|rc|pre|dev|beta|alpha)\.?\d*)$/$1~$2/,
> > \ dversionmangle=s/\+ds(\.?\d+)?$//" \
> > https://codeberg.org/buhtz/hyperorg.git \
> >   refs/tags/v(\d+\S+)
> 
> And uscan will find the most recent version matching the regexp.

I see 3 different regex patterns in this line. Why?

Re: Uscan: watch and changelog

[c.buhtz]

On 2024-03-29 19:26 Andrey Rakhmatullin  wrote:
> On Fri, Mar 29, 2024 at 02:05:41PM +, c.bu...@posteo.jp wrote:
> > The Wiki page  is not
> > up-2-date
> What's wrong with it?

I was not clear in my initial mail, where I only wrote that "Uscan
don't work without having a changelog.". The Wiki page do not mention
that.

But I will edit the page after I figured out some details.

Re: Uscan: watch and changelog

[Carsten Schoenert]

Am 29.03.24 um 15:05 schrieb c.bu...@posteo.jp:


I assume I have not yet understood the purpose of the changelog in
context of uscan. What do I miss?

This is "debian/watch":

version=4
# RegEx in Perl dialect
https://codeberg.org/buhtz/hyperorg/archive/v(\d+).(\d+).(\d+).tar.gz

This is a dummy "debian/changelog":

hyperorg (0.0-dev) UNRELEASED; urgency=low

   * Changes made in this version

  -- Maintainer Name   Thu, 01 Jul 2021 12:00:00
  +


You need to use "opts=mode=git, ...", see the man page of uscan.

e.g. like this


$ cat debian/watch
version=4

opts="mode=git, \
  
uversionmangle=s/(\d)[_\.\-\+]?((RC|rc|pre|dev|beta|alpha)\.?\d*)$/$1~$2/, \
  dversionmangle=s/\+ds(\.?\d+)?$//" \
https://codeberg.org/buhtz/hyperorg.git \
  refs/tags/v(\d+\S+)


And uscan will find the most recent version matching the regexp.

$ uscan --verbose --no-download 
uscan info: uscan (version 2.23.7) See uscan(1) for help

uscan info: Scan watch files in .
uscan info: Check debian/watch and debian/changelog in .
uscan info: package="hyperorg" version="0.0-dev" (as seen in debian/changelog)
uscan info: package="hyperorg" version="0.0" (no epoch/revision)
uscan info: ./debian/changelog sets package="hyperorg" version="0.0"
uscan info: Process watch file at: debian/watch
package = hyperorg
version = 0.0
pkg_dir = .
uscan info: opts: mode=git, 
uversionmangle=s/(\d)[_\.\-\+]?((RC|rc|pre|dev|beta|alpha)\.?\d*)$/$1~$2/, 
dversionmangle=s/\+ds(\.?\d+)?$//
uscan info: line: https://codeberg.org/buhtz/hyperorg.git refs/tags/v(\d+\S+)
uscan info: Parsing mode=git
uscan info: Parsing  
uversionmangle=s/(\d)[_\.\-\+]?((RC|rc|pre|dev|beta|alpha)\.?\d*)$/$1~$2/
uscan info: Parsing  dversionmangle=s/\+ds(\.?\d+)?$//
uscan info: line: https://codeberg.org/buhtz/hyperorg.git refs/tags/v(\d+\S+)
uscan info: Last orig.tar.* tarball version (from debian/changelog): 0.0
uscan info: Last orig.tar.* tarball version (dversionmangled): 0.0
uscan info: Execute: git ls-remote https://codeberg.org/buhtz/hyperorg.git
uscan info: Found the following matching refs:
 refs/tags/v0.1.0 (0.1.0)
 HEAD ()
 refs/heads/fix/131subfolders ()
 refs/heads/fix/30_and_70_links ()
 refs/heads/latest ()
 refs/pull/138/head ()
 refs/pull/139/head ()
uscan info: Looking at $base = https://codeberg.org/buhtz/hyperorg.git with
$filepattern = refs/tags/v(\d+\S+) found
$newfile = refs/tags/v0.1.0
$newversion  = 0.1.0
$lastversion = 0.0
uscan info: Upstream URL(+tag) to download is identified as
https://codeberg.org/buhtz/hyperorg.git refs/tags/v0.1.0
uscan info: Filename (filenamemangled) for downloaded file: 
hyperorg-0.1.0.tar.xz
Newest version of hyperorg on remote site is 0.1.0, local version is 0.0
 => Newer package available from:
=> https://codeberg.org/buhtz/hyperorg.git refs/tags/v0.1.0
uscan info: Scan finished


--
Regards
Carsten

Re: Uscan: watch and changelog

[Andrey Rakhmatullin]

On Fri, Mar 29, 2024 at 02:05:41PM +, c.bu...@posteo.jp wrote:
> The Wiki page  is not up-2-date
What's wrong with it?

-- 
WBR, wRAR


signature.asc
Description: PGP signature

Re: Uscan: watch and changelog

[Andrey Rakhmatullin]

On Fri, Mar 29, 2024 at 07:21:48PM +0500, Andrey Rakhmatullin wrote:
> > I assume I have not yet understood the purpose of the changelog in
> > context of uscan. What do I miss?
> It needs debian/changelog to know the current upstream version of the
> package.
(also this is answered explicitly in uscan(1))



-- 
WBR, wRAR


signature.asc
Description: PGP signature

Re: Uscan: watch and changelog

[Andrey Rakhmatullin]

On Fri, Mar 29, 2024 at 02:05:41PM +, c.bu...@posteo.jp wrote:
> X-Post: 
> 
> Hi,
> 
> try to get uscan working with an upstream repo hosted at Codeberg.org
> (Forgejo based).
> 
> The Wiki page  is not up-2-date
> and I try to figuring out how it works to update that page. Uscan don't
> work without having a changelog. So I created one. But uscan can not
> find my tarball.
> 
> I assume I have not yet understood the purpose of the changelog in
> context of uscan. What do I miss?
It needs debian/changelog to know the current upstream version of the
package.

> version=4
> # RegEx in Perl dialect
> https://codeberg.org/buhtz/hyperorg/archive/v(\d+).(\d+).(\d+).tar.gz
[...]
> uscan info: Requesting URL:
>https://codeberg.org/buhtz/hyperorg/archive/
> uscan warn: In watchfile debian/watch, reading webpage
>   https://codeberg.org/buhtz/hyperorg/archive/ failed: 404 Not Found
> uscan info: Scan finished
I can confirm it's 404.

-- 
WBR, wRAR


signature.asc
Description: PGP signature

Uscan: watch and changelog

[c.buhtz]

X-Post: 

Hi,

try to get uscan working with an upstream repo hosted at Codeberg.org
(Forgejo based).

The Wiki page  is not up-2-date
and I try to figuring out how it works to update that page. Uscan don't
work without having a changelog. So I created one. But uscan can not
find my tarball.

I assume I have not yet understood the purpose of the changelog in
context of uscan. What do I miss?

This is "debian/watch":

version=4
# RegEx in Perl dialect
https://codeberg.org/buhtz/hyperorg/archive/v(\d+).(\d+).(\d+).tar.gz

This is a dummy "debian/changelog":

hyperorg (0.0-dev) UNRELEASED; urgency=low

  * Changes made in this version

 -- Maintainer Name   Thu, 01 Jul 2021 12:00:00
 +


The output of "uscan --no-download --verbose --debug":


uscan info: uscan (version 2.21.3+deb11u1) See uscan(1) for help
uscan info: Scan watch files in .
uscan info: Check debian/watch and debian/changelog in .
uscan info: package="hyperorg" version="0.0-dev" (as seen in
debian/changelog) uscan info: package="hyperorg" version="0.0" (no
epoch/revision) uscan info: ./debian/changelog sets package="hyperorg"
version="0.0" uscan info: Process watch file at: debian/watch
package = hyperorg
version = 0.0
pkg_dir = .
uscan info: Last orig.tar.* tarball version (from debian/changelog): 0.0
uscan info: Last orig.tar.* tarball version (dversionmangled): 0.0
uscan info: Requesting URL:
   https://codeberg.org/buhtz/hyperorg/archive/
uscan warn: In watchfile debian/watch, reading webpage
  https://codeberg.org/buhtz/hyperorg/archive/ failed: 404 Not Found
uscan info: Scan finished