Bug#932853: please someone "git checkout -b bullseye && git push"

[Tomas Pospisek]

Package: release-notes
Severity: wishlist

I have considered forking and branching via Salsa, and then sending the
pull request, but that's not less work. So I'm very kindly asking, if
someone with commit rights could please do a

git checkout -b bullseye && git push

So other then can maybe start forking on that branch and sending
patches/pull requests for already coming in bullseye changes:

#841666, #931785, #932580

Gracias,
*t

-- System Information:
Debian Release: 10.0
APT prefers stable
APT policy: (500, 'stable')
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 4.19.0-5-amd64 (SMP w/8 CPU cores)
Locale: LANG=de_CH.utf8, LC_CTYPE=de_CH.utf8 (charmap=UTF-8), LANGUAGE=de_CH:de (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

[Debian Bug Tracking System]

Processing control commands:

> owner -1 !
Bug #932853 [release-notes] please someone "git checkout -b bullseye && git push"
Owner recorded as Paul Gevers <elb...@debian.org>.

--
932853: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=932853
Debian Bug Tracking System
Contact ow...@bugs.debian.org with problems

[Paul Gevers]

Control: owner -1 !

Hi Tomas,

Thanks a lot that you already want to start working on the bullseye
release-notes.

On 24-07-2019 00:33, Tomas Pospisek wrote:
> I have considered forking and branching via Salsa, and then sending the
> pull request, but that's not less work. So I'm very kindly asking, if
> someone with commit rights could please do a
>
> git checkout -b bullseye && git push
>
> So other then can maybe start forking on that branch and sending
> patches/pull requests for already coming in bullseye changes:
>
> #841666, #931785, #932580

I would wait with bugs like 841666 until it's clear that we actually
want that (at that time). And for bug 932580 it's too early to know what
should be in the text, so we should really defer that to later in the cycle.

That said, I want to prepare a proper branch (with some reworking and
some pruning), so I'll do just this, but not right *now* (there's other
stuff higher on my TODO list). Please, feel free to already propose
text, as that is the hardest part of nearly all release-note bugs.

Paul

[Andrei POPESCU]

On Mi, 24 iul 19, 08:25:01, Paul Gevers wrote:
>
> That said, I want to prepare a proper branch (with some reworking and
> some pruning), so I'll do just this, but not right *now* (there's other
> stuff higher on my TODO list). Please, feel free to already propose
> text, as that is the hardest part of nearly all release-note bugs.

I would like to use this opportunity to propose that for bullseye the
Release Notes should be switched from DocBookXML to reStructuredText.

Reasons:

1. Easier to write due to the lighter markup

2. Easier to translate due to the lighter markup

There are entire strings where translators have to navigate between
the markup.

3. Modern toolchain

4. Transition recently done by Debian Policy and Developer's Reference

While the Release Notes do have significantly more translations,
large parts of it are not reusable between releases.


Kind regards,
Andrei
--
http://wiki.debian.org/FAQsFromDebianUser

[Paul Gevers]

Hi,

On 24-07-2019 21:31, Andrei POPESCU wrote:
> I would like to use this opportunity to propose that for bullseye the
> Release Notes should be switched from DocBookXML to reStructuredText.

I don't think I disagree, as I though about this myself already, but I
don't have the energy to drive this. However, if there are volunteers, I
*think* I welcome this. (As long as translations are saved as much as
possible).

Paul

[Andrei POPESCU]

Control: clone -1 -2
Control: severity -2 wishlist
Control: retitle -2 Please migrate Release Notes to reStructuredText

Ok, I'll have a look at it, though I wouldn't mind if someone is faster
;)

[Debian Bug Tracking System]

Processing control commands:

> clone -1 -2
Bug #932853 [release-notes] please someone "git checkout -b bullseye && git push"
Bug 932853 cloned as bug 932957
> severity -2 wishlist
Bug #932957 [release-notes] please someone "git checkout -b bullseye && git push"
Ignoring request to change severity of Bug 932957 to the same value.

> retitle -2 Please migrate Release Notes to reStructuredText

Bug #932957 [release-notes] please someone "git checkout -b bullseye && git push"
Changed Bug title to 'Please migrate Release Notes to reStructuredText' from 'please someone "git checkout -b bullseye && git push"'.

--
932853: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=932853
932957: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=932957

[Osamu Aoki]

Hi,

On Thu, Jul 25, 2019 at 09:39:12AM +0300, Andrei POPESCU wrote:
> Control: clone -1 -2
> Control: severity -2 wishlist
> Control: retitle -2 Please migrate Release Notes to reStructuredText
>
> On Mi, 24 iul 19, 22:08:04, Paul Gevers wrote:
> > Hi,
> >
> > On 24-07-2019 21:31, Andrei POPESCU wrote:
> > > I would like to use this opportunity to propose that for bullseye the
> > > Release Notes should be switched from DocBookXML to reStructuredText.
> >
> > I don't think I disagree, as I though about this myself already, but I
> > don't have the energy to drive this. However, if there are volunteers, I
> > *think* I welcome this. (As long as translations are saved as much as
> > possible).

Yes. It can be done. I just converted developers-reference and someone
merged it ti main ;-)

If you follow my commit history, all tools and tricks are there.

https://salsa.debian.org/debian/developers-reference

I will work on build script more to make web page looks better. But
source conversion was possible though it is non-trivial.

> Ok, I'll have a look at it, though I wouldn't mind if someone is faster
> ;)

https://salsa.debian.org/debian/developers-reference/blob/1b0940a5c2879a5be3100b0e0f2bee6c5de58bdf/README.rst

This describes general tasks involved.

If someone makes broken PO file by copying some msgstr from random
msgstr, then conversion doesn't work well and it may be cryptic to
debug.

Regards,

Osamu

[Paul Gevers]

Hi Andrei,

On Thu, 25 Jul 2019 22:44:29 +0900 Osamu Aoki <os...@debian.org> wrote:
> Yes. It can be done. I just converted developers-reference and someone
> merged it ti main ;-)
>
> If you follow my commit history, all tools and tricks are there.
>
> https://salsa.debian.org/debian/developers-reference
>
> I will work on build script more to make web page looks better. But
> source conversion was possible though it is non-trivial.
>
> > Ok, I'll have a look at it, though I wouldn't mind if someone is faster
> > ;)
>
> https://salsa.debian.org/debian/developers-reference/blob/1b0940a5c2879a5be3100b0e0f2bee6c5de58bdf/README.rst
>
> This describes general tasks involved.
>
> If someone makes broken PO file by copying some msgstr from random
> msgstr, then conversion doesn't work well and it may be cryptic to
> debug.

Are you still upto doing this change? I'm not expecting you worked on
this recently, but now is a good time to get this on the rails. Should
we first branch bullseye (bug #932853), make the relatively small fixes
there and then work on that branch or do you have a different proposal?

Paul

[Andrei POPESCU]

As mentioned before, this is something I would be interested to work on,
assuming I find the time for it.

In any case, if someone else is interested please go for it.

Regarding branches, wouldn't it make more sense to create a buster
branch and continue work on master? Just asking, I'm fine either way.

[Debian Bug Tracking System]

Processing control commands:

> tags -1 pending
Bug #932853 [release-notes] please someone "git checkout -b bullseye && git push"
Added tag(s) pending.

--
932853: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=932853

[Paul Gevers]

Control: tags -1 pending

Hi,

On 24-07-2019 00:33, Tomas Pospisek wrote:

> Package: release-notes
> Severity: wishlist
>
> I have considered forking and branching via Salsa, and then sending the
> pull request, but that's not less work. So I'm very kindly asking, if
> someone with commit rights could please do a
>
> git checkout -b bullseye && git push
>
> So other then can maybe start forking on that branch and sending
> patches/pull requests for already coming in bullseye changes:
>
> #841666, #931785, #932580

I have requested [1] the webmaster-team to start building the buster
release notes from the buster branch I just created and pushed. Please
wait with making bullseye changes to the master branch until the request
is merged. I intent to upload the first changes with some clean-up,
which is hopefully helpful for the restructuring as there should be less
to restructure.

Paul

[1] https://salsa.debian.org/webmaster-team/cron/merge_requests/4

[Debian Bug Tracking System]

Your message dated Tue, 3 Dec 2019 20:20:15 +0100
with message-id <db687263-5038-d7d2...@debian.org>
and subject line Re: Bug#932853: please someone "git checkout -b bullseye && git push"
has caused the Debian Bug report #932853,
regarding please someone "git checkout -b bullseye && git push"
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact ow...@bugs.debian.org
immediately.)

[Paul Gevers]

Hi Andrei,

On 02-12-2019 00:29, Andrei POPESCU wrote:
> As mentioned before, this is something I would be interested to work on,
> assuming I find the time for it.

Ack.

> In any case, if someone else is interested please go for it.
>
> Regarding branches, wouldn't it make more sense to create a buster
> branch and continue work on master? Just asking, I'm fine either way.

Of course, that's what I meant. I did that in the mean time and master
is now free to start working on this transition to reStructeredText.

Paul

[Holger Wansing]

[[ debian-devel in CC, to get a wider audience regarding reStructuredText ]]


Hi,

I worked on this recently, and I have something like a prototype ready.
It can be found (as html) at
https://people.debian.org/~holgerw/release-notes_sphinx/
while the git repo containing the migration is at
https://salsa.debian.org/holgerw/release-notes


However, I may have some objections against the migration at all:
as far as I know, sphinx/reStructuredText is still lacking some functionality,
which is heavily used in the release-notes.
That is the use of substitutions within URLs.
In docbook speach these were entities, and you could use them in URLs like this:

Please follow the instructions in the <ulink
url="https://www.debian.org/releases/&oldreleasename;/releasenotes">Release
Notes for &debian; &oldrelease;</ulink> to upgrade to &debian;
&oldrelease; first if needed.

Please note the &oldreleasename; in the URL!
I could not get this working with sphinx (if someone knows better, please
contact me!)
In sphinx, I used hardcoded codenames like
https://www.debian.org/releases/bullseye/releasenotes instead, which means,
that there is much work to do to make the release-notes fit for the next release,
while with docbook you only need to change the entity in one place !!!
In sphinx you need to change every single occurence, and don't forget the
translations !!!



Beside this, I need help to adapt the buildchain, to get the possibility of
building the release-notes for the different architectures.
I have no python knowledge, so I will most likely not get this running myself.

And the last point is the integration into the debhelper tools: I don't know
if it is required, to have the release-notes fit for building as a whole
package with sbuild or debuild or similar. Salsa tries to build it via CI
at every push, but currently fails.
However, there is no package "release-notes" in the archive, so currently
it is only a matter of building it on wolkenstein for www.debian.org, right?


Regards
Holger



--
Holger Wansing <hwan...@mailbox.org>
PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076

[Richard Lewis]

On Thu, 18 May 2023 22:39:11 +0200 Holger Wansing <hwan...@mailbox.org> wrote:

> I worked on this recently, and I have something like a prototype ready.
> It can be found (as html) at
> https://people.debian.org/~holgerw/release-notes_sphinx/

I hope the below doesn't come across as negative - it;s not meant to
be: i've been submitted MRs for release-notes and
found the XML syntax adds complexity to the source that mostly only
results in the output using bold or fixed-width:
So it would be great to simplify to rst!

Unfortunately, my first impression is that it the output has quite a
few issues which make it a lot harder to read than
the docbook version - which im sure is because it's still only a
prototype, but thought it might helpful to list the things that jumped
out at me:
- It is a lot more cluttered than the docbook version - it feels
off-putting and dense to read
- it's all a bit 'blue' - i'd suggest red is more on-brand for debian
- the "next"/"prev" links at the bottom-right are white on green ---
I totally missed at first, and found hard to read
- i was a bit confused by the "12.1" version number at the bottom of
every page, and having 'sphinx' reminded me of websites with "hosted
by geocities"
- are the red hyphens in eg the 'deb...' line near the top of
https://people.debian.org/~holgerw/release-notes_sphinx/en/html/issues.html
meant to be red? (maybe it is a syntax error?)
- package names are no longer distinguished from other text (eg 'ntp'
in https://people.debian.org/~holgerw/release-notes_sphinx/en/html/issues.html#changes-to-packages-that-set-the-system-clock)
- the order in the contents pane on the left is a bit...unusual: it
starts with the current section, then does previous, then next, so eg
on chapter 2,
https://people.debian.org/~holgerw/release-notes_sphinx/en/html/whats-new.html
it lists chapters 2, then 1, then 3.
- https://people.debian.org/~holgerw/release-notes_sphinx/en/html/genindex.html
is completely blank
- not sure "show source" on the left is all that useful for readers

I'm sure these are easy to fix!

> while the git repo containing the migration is at
> https://salsa.debian.org/holgerw/release-notes

Im sure i am being dumb, but i couldnt spot where the actual rst files
are? - i still see eg
https://salsa.debian.org/holgerw/release-notes/-/blob/master/en/issues.dbk
in XML

> as far as I know, sphinx/reStructuredText is still lacking some functionality,
> which is heavily used in the release-notes.
> That is the use of substitutions within URLs.

You could always keep the entities and do a 'sed
s/&oldrelease;/bookworm/g' etc before "building" with sphinx.

Actually.... if i click 'show source' l get to
https://people.debian.org/~holgerw/release-notes_sphinx/en/html/_sources/about.rst.txt
which seems to have |RELEASE| and |RELEASENAME| rather than 12 and
bookworm: perhaps sphinx supports entities after all?

[Laura Arjona Reina]

Hello

We have an open bug related to creating a Debian theme for the
documentation that uses Sphinx:

#915583 debian-policy: More attractive sphinx theme, please
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=915583

Unfortunately I think nobody could put on time on this yet.

Other bugs related to Sphinx in Debian documentation that may need to be
taken into account:

#987943 www.debian.org: Developers Reference: Sphinx search
non-functional: searchindex.js missing
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=987943

#1026446
Static javascript resources for Policy and DevRef give 404 errors,
breaking search
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1026446

Kind regards,

El 19/5/23 a las 1:58, Richard Lewis escribió:

--
Laura Arjona Reina
https://wiki.debian.org/LauraArjona

[James Addison]

Followup-For: Bug #932957
X-Debbugs-Cc: hwan...@mailbox.org

Hi Holger,

> Please note the &oldreleasename; in the URL!
> I could not get this working with sphinx (if someone knows better, please
> contact me!)

Could the 'extlinks' feature[1] of Sphinx be helpful to migrate those?

(it allows defining URL pattern aliases, so for example :oldreleasenotes: could
map to https://www.debian.org/releases/bullseye/releasenotes and :releasenotes:
could map to https://www.debian.org/releases/bookworm/releasenotes for D12)

Parameters are supported too, and that could be useful for package-or-filepath
refs (re: grep -r '`.*<' source |grep -o '<https.*>' | sort | uniq -c |sort -n)

> Beside this, I need help to adapt the buildchain, to get the possibility of
> building the release-notes for the different architectures.
> I have no python knowledge, so I will most likely not get this running myself.

I'll try to take a look into that soon to see what I can find out. Do you
know how the current docbook-based build varies by architecture?

Perhaps we can borrow some build scripting from developers-reference and/or
debian-policy.. but I suppose those don't have per-architecture output.

> And the last point is the integration into the debhelper tools: I don't know
> if it is required, to have the release-notes fit for building as a whole
> package with sbuild or debuild or similar. Salsa tries to build it via CI
> at every push, but currently fails.

It's possible I've misunderstood, but would be the goals here to be to get
the release-notes documentation built by CI, and also for it to be distributed
as a Debian package itself?

(someone who knows more may correct me, but I think it would be great to have
the package available for install using apt in addition to the website)

Cheers,
James

[1] - https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html

[RL]

James Addison <j...@jp-hosting.net> writes:

> (someone who knows more may correct me, but I think it would be great to have
> the package available for install using apt in addition to the website)

Interesting idea, but who would use it - won't a release-notes package
always be a whole release out of date?

(and the build-dependencies take a huge amount of disk space for
something you only read once a cycle, alhtough maybe sphinx fixes that)

[Hendrik Boom]

On Sat, May 20, 2023 at 01:06:12PM +0100, RL wrote:
> James Addison <j...@jp-hosting.net> writes:
>
> > (someone who knows more may correct me, but I think it would be great to have
> > the package available for install using apt in addition to the website)
>
> Interesting idea, but who would use it - won't a release-notes package
> always be a whole release out of date?

It would mean that the realease-notes package on your system
would always match the release on your system.

-- hendrik

[Holger Wansing]

Hi,

Richard Lewis <richard.le...@googlemail.com> wrote (Fri, 19 May 2023 00:58:26 +0100):
> On Thu, 18 May 2023 22:39:11 +0200 Holger Wansing <hwan...@mailbox.org> wrote:
> Unfortunately, my first impression is that it the output has quite a
> few issues which make it a lot harder to read than
> the docbook version - which im sure is because it's still only a
> prototype, but thought it might helpful to list the things that jumped
> out at me:
> - It is a lot more cluttered than the docbook version - it feels
> off-putting and dense to read
> - it's all a bit 'blue' - i'd suggest red is more on-brand for debian
> - the "next"/"prev" links at the bottom-right are white on green ---
> I totally missed at first, and found hard to read

I copied style and font settings from developers-reference, another
document, which has been migrated recently from docbook to sphinx.
So I consider this as a quasi-standard at the moment.
I copied it by intent, to get a consistent look for all manuals generated
with sphinx.
We can work on that later on, as Laura already pointed out there is even
a bugreport for this.
So will ignore this for now here.

> - i was a bit confused by the "12.1" version number at the bottom of
> every page, and having 'sphinx' reminded me of websites with "hosted
> by geocities"

The first version I built with sphinx had version displayed
"release-notes 5.0.1" which confused me even more.
Therefore I changed that in the sense of "release-notes version 12 for
Debian release 12". Can still be changed in any way...

> - are the red hyphens in eg the 'deb...' line near the top of
> https://people.debian.org/~holgerw/release-notes_sphinx/en/html/issues.html
> meant to be red? (maybe it is a syntax error?)

I see this in other sphinx-generated manuals as well. So maybe a bug in sphinx?
Or a feature?

> - package names are no longer distinguished from other text (eg 'ntp'
> in https://people.debian.org/~holgerw/release-notes_sphinx/en/html/issues.html#changes-to-packages-that-set-the-system-clock)

good catch, that should be changed - that's an easy one :-)

> - the order in the contents pane on the left is a bit...unusual: it
> starts with the current section, then does previous, then next, so eg
> on chapter 2,
> https://people.debian.org/~holgerw/release-notes_sphinx/en/html/whats-new.html
> it lists chapters 2, then 1, then 3.

Seems to be the default in Sphinx? Currently I cannot see how I could change that.

> - https://people.debian.org/~holgerw/release-notes_sphinx/en/html/genindex.html
> is completely blank

Yes, I already noticed that too.
And it's the same for the debian-policy and the developers-reference...
Needs to be investigated.

> - not sure "show source" on the left is all that useful for readers

That's a feature of sphinx, I guess.
And if a reader finds an error, or wants to make a proposal for a change, he
can easily access the source code and provide a patch against this.
So that's a good feature!

> I'm sure these are easy to fix!
>
> > while the git repo containing the migration is at
> > https://salsa.debian.org/holgerw/release-notes
>
> Im sure i am being dumb, but i couldnt spot where the actual rst files
> are? - i still see eg
> https://salsa.debian.org/holgerw/release-notes/-/blob/master/en/issues.dbk
> in XML

I have removed several old files from the repo now, amongst others the dbk
files in en.
The new rst files for English are in ./source/ (default for sphinx AFAICT).

> > as far as I know, sphinx/reStructuredText is still lacking some functionality,
> > which is heavily used in the release-notes.
> > That is the use of substitutions within URLs.
>
> You could always keep the entities and do a 'sed
> s/&oldrelease;/bookworm/g' etc before "building" with sphinx.

That will not work.
You cannot replace all 'bullseye' by 'bookworm'. There are places, where the
'bullseye' needs to stay. So that needs to be done selective one-by-one.

> Actually.... if i click 'show source' l get to
> https://people.debian.org/~holgerw/release-notes_sphinx/en/html/_sources/about.rst.txt
> which seems to have |RELEASE| and |RELEASENAME| rather than 12 and
> bookworm: perhaps sphinx supports entities after all?

Sure, in sphinx that's called "substitution" and I use it already very much in
this manual.
The point is, that they do not work in all situations, where they did in docbook
(at least this is my current state of knowledge).

[Holger Wansing]

Hi,

James Addison <j...@jp-hosting.net> wrote (Fri, 19 May 2023 23:28:55 +0100):
> > Please note the &oldreleasename; in the URL!
> > I could not get this working with sphinx (if someone knows better, please
> > contact me!)
>
> Could the 'extlinks' feature[1] of Sphinx be helpful to migrate those?

Yes, thanks for the pointer! I used that now to get the manpage links fixed!

> (it allows defining URL pattern aliases, so for example :oldreleasenotes: could
> map to https://www.debian.org/releases/bullseye/releasenotes and :releasenotes:
> could map to https://www.debian.org/releases/bookworm/releasenotes for D12)
>
> Parameters are supported too, and that could be useful for package-or-filepath
> refs (re: grep -r '`.*<' source |grep -o '<https.*>' | sort | uniq -c |sort -n)

The drawback is, it is not as flexible as the entities in docbook.
For example, there is the following URL in this manual in docbook:

&url-debian-mirror-eg;/debian/dists/&releasename;/main/binary-&architecture;/...

You see, there are three entites in this URL!
This seems to be not supported by extlinks :-((

> > Beside this, I need help to adapt the buildchain, to get the possibility of
> > building the release-notes for the different architectures.
> > I have no python knowledge, so I will most likely not get this running myself.
>
> I'll try to take a look into that soon to see what I can find out. Do you
> know how the current docbook-based build varies by architecture?

There are some chapters, which are only visible for specific architectures, like
in installing.dbk:

<section id="cloud" arch="amd64;arm64;ppc64el" condition="fixme">
<title>Cloud installations</title>
<para>
The <ulink url="&url-cloud-team;">cloud team</ulink> publishes
Debian &releasename; for several popular cloud computing services
including:

> Perhaps we can borrow some build scripting from developers-reference and/or
> debian-policy.. but I suppose those don't have per-architecture output.

I think so, yes. That will be of no help, I fear...

> > And the last point is the integration into the debhelper tools: I don't know
> > if it is required, to have the release-notes fit for building as a whole
> > package with sbuild or debuild or similar. Salsa tries to build it via CI
> > at every push, but currently fails.
>
> It's possible I've misunderstood, but would be the goals here to be to get
> the release-notes documentation built by CI, and also for it to be distributed
> as a Debian package itself?
>
> (someone who knows more may correct me, but I think it would be great to have
> the package available for install using apt in addition to the website)

That was my first thought as well, yes.

[Holger Wansing]

[[ Replying to two mails in one ]]


Hi,

Holger Wansing <hwan...@mailbox.org> wrote (Sat, 20 May 2023 23:26:47 +0200):
> James Addison <j...@jp-hosting.net> wrote (Fri, 19 May 2023 23:28:55 +0100):
> > > Please note the &oldreleasename; in the URL!
> > > I could not get this working with sphinx (if someone knows better, please
> > > contact me!)
> >
> > Could the 'extlinks' feature[1] of Sphinx be helpful to migrate those?
>
> Yes, thanks for the pointer! I used that now to get the manpage links fixed!
>
> > (it allows defining URL pattern aliases, so for example :oldreleasenotes: could
> > map to https://www.debian.org/releases/bullseye/releasenotes and :releasenotes:
> > could map to https://www.debian.org/releases/bookworm/releasenotes for D12)
> >
> > Parameters are supported too, and that could be useful for package-or-filepath
> > refs (re: grep -r '`.*<' source |grep -o '<https.*>' | sort | uniq -c |sort -n)
>
> The drawback is, it is not as flexible as the entities in docbook.
> For example, there is the following URL in this manual in docbook:
>
> &url-debian-mirror-eg;/debian/dists/&releasename;/main/binary-&architecture;/...
>
> You see, there are three entites in this URL!
> This seems to be not supported by extlinks :-((

I focused a bit too much on the URL front here.
There is also a problem using entities (or now called substitutions) in
quoted lines like

deb https://deb.debian.org/debian RELEASENAME main contrib

or

# script -t 2>~/upgrade-RELEASENAMEstep.time -a ~/upgrade-RELEASENAMEstep.script

These also do not work.
That's the biggest blocker in the upgrading chapter IMHO.

Hi,

I fixed them, and updated the html files at
https://people.debian.org/~holgerw/release-notes_sphinx/

[RL]

Hendrik Boom <hen...@topoi.pooq.com> writes:

> On Sat, May 20, 2023 at 01:06:12PM +0100, RL wrote:
>> James Addison <j...@jp-hosting.net> writes:
>>
>> > (someone who knows more may correct me, but I think it would be great to have
>> > the package available for install using apt in addition to the website)
>>
>> Interesting idea, but who would use it - won't a release-notes package
>> always be a whole release out of date?
>
> It would mean that the realease-notes package on your system
> would always match the release on your system.

Can i ask why that is beneficial: how it would make your life better? i
know you are not saying the website version is going away, but i'm
afraid i don't understand the use-case for a packaged version. Maybe i
am missing out on something.

For me, the value of release-notes is to know what things need to be
thought about as part of the upgrade. Especially things that need to
happen before the dist-upgrade, such as 'do not upgrade an i386 system
unless it is really i586', or 'this package is going away': sometimes, i
wouldnt start the upgrade until i knew what was replacing removed
packages with (see the current warning about gnome and orca for
example).

I also wonder how practical it is to achieve. At the moment, bookworm is
frozen, and release-notes are work-in-progress - there are still open
bugs with draft text and open merge-requests. Is it realistic for
everything in release-notes to be finished (including translations) and
for someone to upload a package ensure it makes it into bookworm debian
during the full freeze before the release happens?

I suppose you envision bookworm releasing with a best-efforts version,
and re-uploading as part of point releases?

If it is a package, shouldnt it be available in man/roff format so it is
always readable from a text console?

[RL]

Holger Wansing <hwan...@mailbox.org> writes:

>> > as far as I know, sphinx/reStructuredText is still lacking some functionality,
>> > which is heavily used in the release-notes.
>> > That is the use of substitutions within URLs.
>>
>> You could always keep the entities and do a 'sed
>> s/&oldrelease;/bookworm/g' etc before "building" with sphinx.
>

> That will not work.
> You cannot replace all 'bullseye' by 'bookworm'. There are places, where the
> 'bullseye' needs to stay. So that needs to be done selective one-by-one.

I think you misunderstood: i am suggesting to make the .rst a hybrid
syntax, which is mostly rst but with some 'entities'
- where text is the same between releases (and where |RELEASENAME|
doesnt do the rigt thing), we write '&oldrelease;' in the source
- where text is about a specific release we write 'bookworm'
(which is already what the README on salsa recommends)
- build now involves
a) pre-process with sed to replace &oldrelease; -> bullseye etc
this produces a temp file with a pure .rst syntax
b) run that temp file through sphinx to get the html

- on the next release, all that needs to happen is to update the sed script in (a) to be use the new release name
(as needs to happen with the XML entities when using docbook)

bit hacky perhaps, but doesnt it work as well as what we have today?

How does this all work with translations btw?

[James Addison]

Followup-For: Bug #932957
X-Debbugs-Cc: hwan...@mailbox.org

On Sun, 21 May 2023 10:16:36 +0200, Holger wrote:
> There is also a problem using entities (or now called substitutions) in
> quoted lines like

> deb https://deb.debian.org/debian RELEASENAME main contrib

Ok, yep - I understand the problem there now, and have experimented with it a
bit locally. Roughly speaking: substitutions aren't possible within literal
quote blocks (there is a '::' a couple of lines before the mentioned line, and
adding the pipe '|' symbols around the substitution label doesn't make a
difference within literal blocks)

Not sure what to suggest yet as an alternative, though...

[James Addison]

Followup-For: Bug #932957
X-Debbugs-Cc: hwan...@mailbox.org

On Mon, 22 May 2023 23:40:46 +0100, James wrote:
> On Sun, 21 May 2023 10:16:36 +0200, Holger wrote:
> > There is also a problem using entities (or now called substitutions) in
> > quoted lines like
>
> > deb https://deb.debian.org/debian RELEASENAME main contrib
>
> Ok, yep - I understand the problem there now, and have experimented with it a
> bit locally. Roughly speaking: substitutions aren't possible within literal
> quote blocks (there is a '::' a couple of lines before the mentioned line, and
> adding the pipe '|' symbols around the substitution label doesn't make a
> difference within literal blocks)

It looks like the fix for that is to convert those literal ('::') blocks into
parsed-literal[1] ('.. parsed-literal::') blocks.

[1] - https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal

[Paul Gevers]

Hi Holger,

On 18-05-2023 22:39, Holger Wansing wrote:
> I worked on this recently, and I have something like a prototype ready.

Thanks a lot for working on this. I'm a bit swamped with last minute
things that need to happen before the release of bookworm, so I don't
expect to have time to look at this until after the release.

Paul

[Holger Wansing]

Hi Paul,

As I wrote, I see this as a prototype, and thus I don't expected it to be a thing to
happen before releasing bookworm.


Holger



--
Sent from /e/ OS on Fairphone3

[Holger Wansing]

Hi,

Yes, that works! Thanks for this!

I have therefore changed all literal ('::') blocks into parsed-literal

('.. parsed-literal::') blocks.

In output, there seems to be no difference (at least in this document), and
this way it's easier for future editors (no need to distinguish between
two different versions of quoted blocks).


Holger

[James Addison]

Package: release-notes

Followup-For: Bug #932957
X-Debbugs-Cc: hwan...@mailbox.org

Hi Holger,

I noticed one more problem with the output of the ReST release-notes:

Filtering of architecture-specific sections does not seem to be taking place,
so the 'Supported Architectures'[1] section for AMD64 currently contains the
text:

The ARCH-TITLE support (known as the Debian architecture amd64) now requires the “long NOP” instruction. Please refer to Baseline for 64-bit PC is now i686 for more information.

(the ARCH-TITLE placeholder is probably a small fixup - the problem I'd like
to draw attention to is the reference to 64-bit PC / amd64 as i686)

In the Docbook source, there is an 'arch="i386"' annotation[2] on the section's
XML element, so perhaps that is used to filter the content.

Cheers,
James

[1] - https://people.debian.org/~holgerw/release-notes_sphinx/en/html/whats-new.html#supported-architectures

[2] - https://salsa.debian.org/ddp-team/release-notes/-/blob/698b757e098b7d7ccd7b34b5bb9bda333155fd11/en/whats-new.dbk#L71

[Stéphane Blondon]

> Richard Lewis <richard.le...@googlemail.com> wrote (Fri, 19 May 2023 00:58:26 +0100):

> > - are the red hyphens in eg the 'deb...' line near the top of
> > https://people.debian.org/~holgerw/release-notes_sphinx/en/html/issues.html
> > meant to be red? (maybe it is a syntax error?)
>

Sphinx uses Pygments to highlight source code. I guess no language is defined so Sphinx uses a wrong lexer. We should force Sphinx to use 'SourceListLexer' with:

.. code-block :: sources.list

[Stéphane Blondon]

Le dim. 28 mai 2023 à 13:16, Stéphane Blondon
<stephane...@gmail.com> a écrit :

> Sphinx uses Pygments to highlight source code. I guess no language is defined so Sphinx uses a wrong lexer. We should force Sphinx to use 'SourceListLexer' with:
> .. code-block :: sources.list

I sent a Merge Request on Holger's repository to implement it:
https://salsa.debian.org/holgerw/release-notes/-/merge_requests/2

[Holger Wansing]

Hi,

The highlighting feature is great, thanks for pointing this out!
However, we cannot use it here in most cases for sources.list entries,
since resolving substitutions does not work within such lines :-(
like in

deb https://deb.debian.org/debian |RELEASENAME| main contrib

But in many cases the highlighting gives us a great benefit, so I will
merge your MR and adapt the rare cases, where it does not work.

Thanks again!

Holger

[Holger Wansing]

Hi,

James Addison <j...@jp-hosting.net> wrote (Fri, 26 May 2023 13:02:53 +0100):
> I noticed one more problem with the output of the ReST release-notes:
>
> Filtering of architecture-specific sections does not seem to be taking place,
> so the 'Supported Architectures'[1] section for AMD64 currently contains the
> text:
>
> The ARCH-TITLE support (known as the Debian architecture amd64) now requires the “long NOP” instruction. Please refer to Baseline for 64-bit PC is now i686 for more information.
>
> (the ARCH-TITLE placeholder is probably a small fixup - the problem I'd like
> to draw attention to is the reference to 64-bit PC / amd64 as i686)
>
> In the Docbook source, there is an 'arch="i386"' annotation[2] on the section's
> XML element, so perhaps that is used to filter the content.

Yes, filtering the content for the different architectures does not work yet.
That's one open point, where I have requested help for.

I have fixed the forgotten ARCH-TITLE placeholder now.

[James Addison]

Package: release-notes
Followup-For: Bug #932957
X-Debbugs-Cc: hwan...@mailbox.org

Oops - there were a couple of problems with my most recent message here:

* Forgot to cc you on the details, Holger (in short summary: the ReST 'only'
directive[1] may be helpful here, and could be used with a '-t <tag>'
command-line option to sphinx-build from the Makefile)

* I didn't read the documentation! The tags for the 'only' directive must be
valid Python identifiers, so 'arch_i386' would work as a tag name, but
'arch-i386' (that I had suggested previously) would not.

[1] - https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#including-content-based-on-tags

[James Addison]

Package: release-notes
Followup-For: Bug #932957

> Yes, filtering the content for the different architectures does not work yet.

Ah, and I said I would help with that :)

Although I don't yet know exactly how it's going to interact with the build
process, I _think_ that a feature we could use for this is the 'only'
directive:

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-only

Although this could benefit from more thought, initially I suggest we adopt a
tag format something like 'arch-{debarch}' to handle this (so the conditional
clause here would be placed within a '.. only:: arch-i386' block.

From there, we could pass the corresponding tag on the commandline using the
'-t' option, I guess in the Makefile:

https://salsa.debian.org/holgerw/release-notes/-/blob/a2ba839790573915a80db75405abf8ef9212ac8e/Makefile#L103

[Holger Wansing]

Hi,

James Addison <j...@jp-hosting.net> wrote (Mon, 29 May 2023 00:18:36 +0100):
> [[Holger Wansing wrote:]]

I have implemented such things now in
https://salsa.debian.org/holgerw/release-notes/-/commit/0304c87400432e1905d1bb04d39468a632876978
as a first step for arch-depending filtering.

Works so far, if the wanted arch is set in the Makefile (line 175) via the -t option.

Thanks for your help on this!

Now we just need an infrastructure, to loop over all architectures for build targets...

[Holger Wansing]

Some status update:

I managed to expand the Makefile, to build r-n for different archs for all
languages and for formats text+pdf+nopdf+html:

https://salsa.debian.org/holgerw/release-notes/-/commits/master?ref_type=heads


Open points:

- In this version, it builds for amd64+armel+i386+ppc64el only. No problem,
to expand this for more archs though.
- For now, I have separate conf.py files for the different archs, which I copy
in place before starting the builds; needs to be replaced by some sed mechanism.
- The list of archs is hardcoded in the Makefile for now.
- The target 'make install' is not ready; you can only build with
'make text|make pdf|make nopdf|make html|make all' and get the results in
the build dir.

[Stuart Prescott]

Hi Holger

Thanks for working on this :)

> - The list of archs is hardcoded in the Makefile for now.

The following might provide you with some useful way of not hard-coding
such information:

curl -s 'https://api.ftp-master.debian.org/suite/bookworm'

(pipe that into « jq -r '.architectures[]' » to get just the archs as
plain text)

You might want to make that a 'maintainer-run' step rather than is run
occasionally as part of preparing a release, rather than as a build time
step. That is, the maintainer runs that from a machine with internet
access to find the list of archs that should be used; this is then
cached in the repo until it is next refreshed. There is precedent for
this 'maintainer-run' step in various "make dist' mechanisms (from the
autotools world) and how the dh-python packages prepares a cache of
known python modules in the archive for later module→package translation.

There has been talk for a while about how we might avoid baking in
internal metadata in packages and there might be more inspiration on how
to do this in other parts of the project:

https://wiki.debian.org/SuitesAndReposExtension

(there are already a couple of entries there for the release notes)

cheers
Stuart



--
Stuart Prescott http://www.nanonanonano.net/ stu...@nanonanonano.net
Debian Developer http://www.debian.org/ stu...@debian.org
GPG fingerprint 90E2 D2C1 AD14 6A1B 7EBB 891D BBC1 7EBB 1396 F2F7

[James Addison]

unarchive 977358
reopen 977358
blocks 977358 by 952450

Although this was documented for bullseye, the underlying cause
remains, and I think that it could be valuable for users to continue
to have this documentation available.

I've tested that the previously-added guidance from the bullseye
release notes remains valid and works on a bookworm system, and have
pushed a branch[1] to Salsa to restore the documentation.

Bugreport #952450 tracks a longer-term fix, and once that is resolved
I think it'd be fine to drop this note from the release-notes.

(for most other temporary/transitional release note issues, I think
it's fine to drop them between releases - this one seems to me like an
exception)

It's possible that this is too late to be included in the bookworm
release notes (and my apologies, if so). If not, though, I'll provide
a similar commit for the reStructuredText migration (cc'd).

[1] - https://salsa.debian.org/jayaddison/release-notes-docbook/-/tree/bug-977358/retain-issue-note

[Holger Wansing]

Hi Stuart,

Stuart Prescott <stu...@debian.org> wrote (Sat, 3 Jun 2023 14:45:46 +1000):
> > - The list of archs is hardcoded in the Makefile for now.
>
> The following might provide you with some useful way of not hard-coding
> such information:
>
> curl -s 'https://api.ftp-master.debian.org/suite/bookworm'
>
> (pipe that into « jq -r '.architectures[]' » to get just the archs as
> plain text)

I managed to get a list of all relevant architectures via
curl -s 'https://api.ftp-master.debian.org/suite/testing' | jq -r '.architectures[]' | grep -v all | grep -v source

> You might want to make that a 'maintainer-run' step rather than is run
> occasionally as part of preparing a release, rather than as a build time
> step. That is, the maintainer runs that from a machine with internet
> access to find the list of archs that should be used; this is then
> cached in the repo until it is next refreshed. There is precedent for
> this 'maintainer-run' step in various "make dist' mechanisms (from the
> autotools world) and how the dh-python packages prepares a cache of
> known python modules in the archive for later module→package translation.

I created a prepare-release.sh script, which can be used to prepare the
release-notes for the next stable.
That script creates an archlist file, which holds the relevant archs for
the current testing.

Thanks for helping me with that!

> There has been talk for a while about how we might avoid baking in
> internal metadata in packages and there might be more inspiration on how
> to do this in other parts of the project:
>
> https://wiki.debian.org/SuitesAndReposExtension
>
> (there are already a couple of entries there for the release notes)

Shouldn't the above solution be added to that wiki page?
(I don't see it there, right?)

[Paul Gevers]

Hi,

On 20-05-2023 23:26, Holger Wansing wrote:
>>> And the last point is the integration into the debhelper tools: I don't know
>>> if it is required, to have the release-notes fit for building as a whole
>>> package with sbuild or debuild or similar. Salsa tries to build it via CI
>>> at every push, but currently fails.
>>
>> It's possible I've misunderstood, but would be the goals here to be to get
>> the release-notes documentation built by CI, and also for it to be distributed
>> as a Debian package itself?
>>
>> (someone who knows more may correct me, but I think it would be great to have
>> the package available for install using apt in addition to the website)
>
> That was my first thought as well, yes.

At the price this may have been answered already, I think the current
release notes are not packages because typically a lot of the relevant
changes get updated in the weeks *around* the release. So one would have
an outdated release notes. On top of that, most "issues to be aware of
while upgrading" won't be so useful if you already upgraded. Having said
that, I don't mind we make it a package, we just need to be clear of
what the purpose is inside a release.

Also, on the topic of arch-specific builds, I not convinced it's worth a
lot of effort. The amount of arch specific pieces is rather limited, so
I wouldn't mind if we drop that altogether. Currently, we don't do a
great service to people that need to support multiple architectures,
because they need to *search* for the delta's, so I wouldn't be
surprised if it is even better if we drop it.

Paul

[Holger Wansing]

Hi,

Paul Gevers <elb...@debian.org> wrote (Wed, 14 Jun 2023 21:19:00 +0200):
> Also, on the topic of arch-specific builds, I not convinced it's worth a
> lot of effort. The amount of arch specific pieces is rather limited, so
> I wouldn't mind if we drop that altogether. Currently, we don't do a
> great service to people that need to support multiple architectures,
> because they need to *search* for the delta's, so I wouldn't be
> surprised if it is even better if we drop it.

From the technical side, I managed to get the arch-specific builds done in
the meantime basically; so no problem anymore there - theoretically.

On the other side, I also thought about the arch-specific differences, and
given they are only rather small, my assumption was, that it's maybe not worth
it to differentiate between archs, when it comes to filtering out content
of r-n depending on the architecture.
But even if we leave that point out, there are some arch-dependent links like
http://mirrors.kernel.org/debian/dists/bookworm/main/binary-amd64/...
in chapter 4.3.1
https://www.debian.org/releases/stable/amd64/release-notes/ch-upgrading.en.html#network

So, we still need to build the release-notes differentiated by archs
(based on the current content).



However, that does not mean, we could not change our base rules, so that
filtering out chapters based on architecture is no longer used.
I would vote for this solution, yes.

[Holger Wansing]

Hi,

Thinking a bit more about this, I wonder if we could indeed get rid of
architecture-dependent r-n at all.

If all paragraphs/chapters are visible for all archs anyway, there are
only two situations where the arch shortname (amd64, i386 etc.) is used
in URLs. That is in
https://www.debian.org/releases/stable/amd64/release-notes/ch-upgrading.en.html#network
and
https://www.debian.org/releases/stable/amd64/release-notes/ch-upgrading.en.html#localmirror

<quote>
For example, suppose your closest Debian mirror is http://mirrors.kernel.org.
If you inspect that mirror with a web browser, you will notice that the main
directories are organized like this:

http://mirrors.kernel.org/debian/dists/bookworm/main/binary-amd64/...
http://mirrors.kernel.org/debian/dists/bookworm/contrib/binary-amd64/...

To configure APT to use a given mirror, add a line like this (again,
assuming you are using main and contrib):

deb http://mirrors.kernel.org/debian bookworm main contrib
</quote>

So, the arch-dependent directories on the mirrors are mentioned here, but the
arch part is not really relevant here. We could just skip the last part of
the URL and point to
http://mirrors.kernel.org/debian/dists/bookworm/main/..
and that's it. The same counts for the second occurrence of arch shortname.

That gives us the possibility, to simplify the whole r-n thing to only build
one generic release-notes variant for all archs, in the different languages,
and we are done.

How does that sound?

[Paul Gevers]

Hi Holger,

On 18-06-2023 14:32, Holger Wansing wrote:
> We could just skip the last part of
> the URL and point to
> http://mirrors.kernel.org/debian/dists/bookworm/main/..
> and that's it.

I agree.

Paul

[Holger Wansing]

Hi,

Holger Wansing <hwan...@mailbox.org> wrote (Sun, 18 Jun 2023 14:32:25 +0200):
> That gives us the possibility, to simplify the whole r-n thing to only build
> one generic release-notes variant for all archs, in the different languages,
> and we are done.
>
> How does that sound?

Status update:

1.
I have reduced the build chain to only build one generic arch-independent
variant of r-n, for all languages. It has all the content, and it's just named
"Release Notes for Debian 12 (bookworm)"
no longer mentioning any arch name in the title, and without any arch-name
reference in the whole document.

Note: If we decide to go with such approach, the website would need an
overhaul because of this!!!


2.
I added some sort of a basic-level draft mode:
Sphinx does not have support for a watermark, as dblatex had (at least not
in the sphinx version/packages we have in Debian; there is a contrib
extension 'sphinxmark' which does that, but that's not available in
Sphinx mainstream).

So I have just added a bold
"DRAFT MODE - in development for the next release"
on the html index page.

Maybe someone has better ideas?
AFAICS we could go forward with this via using a different html layout
template, or using a different theme, but I could not get that running.


The current version can still be found at
https://people.debian.org/~holgerw/release-notes_sphinx
for all languages and in html|text|pdf
(or grab the results from Salsa's CI at
https://salsa.debian.org/holgerw/release-notes/-/pipelines
which builds fine now.)

[Paul Gevers]

Hi Holger,

On 25-06-2023 14:11, Holger Wansing wrote:
> I have reduced the build chain to only build one generic arch-independent
> variant of r-n, for all languages. It has all the content, and it's just named
> "Release Notes for Debian 12 (bookworm)"
> no longer mentioning any arch name in the title, and without any arch-name
> reference in the whole document.

Great.

> Note: If we decide to go with such approach, the website would need an
> overhaul because of this!!!

Sure.

> I added some sort of a basic-level draft mode:

To be fair, I'm not very attached to it. During the previous release
(bullseye) I even had the notes in non-draft mode for (nearly) the whole
preparation period. I'm not sure anybody took the notes for something
they were not.

Paul

[Holger Wansing]

Hi,

I have worked out the last big blocker for this migration now.
That is, to allow the build on wolkenstein, which is happening via the
parts/7release-notes script in webmaster-team/cron git repo.

I forked that repo and committed my changings there:
https://salsa.debian.org/holgerw/cron/-/commits/master?ref_type=heads


Tests were successful, the results can be found on
https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/,
in the exact same structure as they would appear on the Debian website.
The release-notes dir
https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/
holds the html files for all languages, but content negotiation does not
work there apparently; and the apache server does not show a file browser
view for that directory.
You can find German for example via
https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/index.de.html
or Dutch via
https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/index.nl.html
And remember, there is only one generic variant for all archs now!



The build process in 7releases-notes is now different between stable
and testing: stable is still on docbook, and testing is on sphinx/
reStructuredText.

So, when the time comes, we could create a bookworm branch for r-n,
migrate master to sphinx, and activate the build on wolkenstein for
master/trixie.
That way, we have a comfortable test time, to get everything ready
on the website (Note: there are changings to do on the website then),
while the r-n for trixie are not in public attention.


So long

[Richard Lewis]

Holger Wansing <hwan...@mailbox.org> writes:

> Tests were successful, the results can be found on
> https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/,
> in the exact same structure as they would appear on the Debian
> website.

nice - it looks like it's come on a long way from the previous version.

A couple of minor things in the content:

in [0] the '#' is meant to indicate 'run this as root', but the rst has
'.. code-block:: shell' so the commands are being formatted as a
comment.

in [1] the second para is dummy text that is commented out in the XML
version. In the rst 'source' (but not visible in the html) there are
also some odd chars around 'formal' (the quotes seems to be fine in the
sections above).

[1] https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#things-to-do-post-upgrade-before-rebooting

in [2] there seems to be an extra space in the RH column in
'c a-certificates-java' (in the source there is a linebreak after the c)

[2] https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#known-severe-bugs

(And
https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/about.en.html#sources-for-this-document
will need an update! - as will the README in salsa)

[Holger Wansing]

Hi,

Richard Lewis <richard.le...@googlemail.com> wrote (Sun, 30 Jul 2023 11:10:10 +0100):
> in [0] the '#' is meant to indicate 'run this as root', but the rst has
> '.. code-block:: shell' so the commands are being formatted as a
> comment.

Yes, there are different methods for including quoted material, and they are
somewhat tricky sometimes.

I may lack detailed experience on this, so need more details:
- What's the exact URL where you found this? (there was no such link as [0])
- What makes you think, that the commands are formatted as comment?
Is it the font color or what?

> in [1] the second para is dummy text that is commented out in the XML
> version.

This reST version of r-n is kind of a draft, so it's not as ready as it would
be when in publication mode. Such details slipped through, sorry.

> In the rst 'source' (but not visible in the html) there are
> also some odd chars around 'formal' (the quotes seems to be fine in the
> sections above).

Reason for this was: there were different quote signs used in those sections.
I changed “this” quotes into "this" ones. That solves the problem.

> [1] https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#things-to-do-post-upgrade-before-rebooting
>
> in [2] there seems to be an extra space in the RH column in
> 'c a-certificates-java' (in the source there is a linebreak after the c)

Also fixed.
However, this section is also kind of a placeholder, it will get replaced
with a updated list. But fixing the format is a good idea nevertheless.

> [2] https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#known-severe-bugs
>
> (And
> https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/about.en.html#sources-for-this-document
> will need an update! - as will the README in salsa)

For sure. I am aware of this.

[Richard Lewis]

Holger Wansing <hwan...@mailbox.org> writes:

> Richard Lewis <richard.le...@googlemail.com> wrote (Sun, 30 Jul 2023 11:10:10 +0100):

>> in [0] the '#' is meant to indicate 'run this as root', but the rst has
>> '.. code-block:: shell' so the commands are being formatted as a
>> comment.
>

> Yes, there are different methods for including quoted material, and they are
> somewhat tricky sometimes.
>
> I may lack detailed experience on this, so need more details:
> - What's the exact URL where you found this? (there was no such link as [0])
> - What makes you think, that the commands are formatted as comment?
> Is it the font color or what?

sorry - it's the use of italic in eg '# apt-mark auto rsyslog'
https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#changes-to-system-logging


i found
https://stackoverflow.com/questions/16397794/how-to-show-terminal-shell-code-snippets-in-sphinx
which i think says that 'code-block:: console' might be better than
'code-block:: shell', but i may be misunderstanding that page

[Holger Wansing]

Hi,

Richard Lewis <richard.le...@googlemail.com> wrote (Sun, 30 Jul 2023 21:32:36 +0100):
> sorry - it's the use of italic in eg '# apt-mark auto rsyslog'
> https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#changes-to-system-logging
>
>
> i found
> https://stackoverflow.com/questions/16397794/how-to-show-terminal-shell-code-snippets-in-sphinx
> which i think says that 'code-block:: console' might be better than
> 'code-block:: shell', but i may be misunderstanding that page

Yes, 'code-block:: console' indeed works fine for most occurrences.
So I unified
'code-block:: text'
'code-block:: shell'
'code-block:: shell-session'
to
'code-block:: console'


The only case where that doesn't work is, when substitutions are included.
They only work within '.. parsed-literal::' sadly :-(

[Holger Wansing]

Hi,

Paul Gevers <elb...@debian.org> wrote (Thu, 24 Aug 2023 14:10:41 +0200):
> Hi Holger,

>
> On 29-07-2023 21:29, Holger Wansing wrote:
> > I have worked out the last big blocker for this migration now.
> > That is, to allow the build on wolkenstein, which is happening via the
> > parts/7release-notes script in webmaster-team/cron git repo.
>

> I have just requested webmaster to switch the bookworm build from the
> master branch to the bookworm branch [1]. After that request gets merged
> and deployed, I'd like you to publish your work in the master branch
> such that we can work from there (and see the results too [2]). Because
> in your worked we stopped making notes per architecture, we probably
> need to make further changes to the webmaster archive, but let's first
> build something.

Please note, that the webmaster-team/cron script has to be overworked,
to deal with the new reST format.
I have prepared that in
https://salsa.debian.org/holgerw/cron/-/commits/master?ref_type=heads
(as written above).


Rationale:
It is common for all documentation packages we have on www.debian/doc,
that the package itself creates files during package build, which do not
fit into the webpage system (main point: content negotiation).
To deal with this, someone from the ddp team has developed a script
(long ago; don't know by head who was this), that renames the files
to fit the webpage (basically this is about adding the language
extension). This is in webmaster-team/cron/parts/7doc.

With the old docbook release-notes, this has been dealed with directly
in the build script.
Now in the new reST world, I have basically copied the whole build
mechanism from the developers-reference as is, with the intention to
rely on the mechanism from the 7doc script mentioned above
(the 7doc script has been adapted explicitly for reST/sphinx).

The release-notes have always been a corner case when it comes to how
they were built, compared to all other docs:
the r-n are built from source explicitly for the website, while for all
the other documentation we just unpack their binary debian packages,
rename the files via 7doc and that's it.
This does not work for the r-n, because there is no Debian package existing
for them.
So the r-n are always a separate world.
Based on that, I have kept the 7doc mechanism separately too, copied into
the new 7release-notes.
Means the 7release-notes script from webmaster-team/cron git repo
gets extremely expanded, to copy (and adjust) the functionality from 7doc.

I have developed and tested this here locally, it should work fine.

So I have created a merge request to get this done for the website:
https://salsa.debian.org/webmaster-team/cron/-/merge_requests/13


Best regards

[Holger Wansing]

Package: www.debian.org
Severity: normal

Paul Gevers <elb...@debian.org> wrote (Thu, 24 Aug 2023 14:10:41 +0200):
> Hi Holger,
>
> On 29-07-2023 21:29, Holger Wansing wrote:

> > I have worked out the last big blocker for this migration now.
> > That is, to allow the build on wolkenstein, which is happening via the
> > parts/7release-notes script in webmaster-team/cron git repo.
>

> I have just requested webmaster to switch the bookworm build from the
> master branch to the bookworm branch [1]. After that request gets merged
> and deployed, I'd like you to publish your work in the master branch
> such that we can work from there (and see the results too [2]). Because
> in your worked we stopped making notes per architecture, we probably
> need to make further changes to the webmaster archive, but let's first
> build something.

Hey webmaster team,

please consider MR13 in webmaster's cron repo:

https://salsa.debian.org/webmaster-team/cron/-/merge_requests/13


Thanks

[Holger Wansing]

Package: www.debian.org
Severity: normal

[Re-send once more; first try one month ago did not make it into the BTS]

Paul Gevers <elb...@debian.org> wrote (Thu, 24 Aug 2023 14:10:41 +0200):
> Hi Holger,
>
> On 29-07-2023 21:29, Holger Wansing wrote:

> > I have worked out the last big blocker for this migration now.
> > That is, to allow the build on wolkenstein, which is happening via the
> > parts/7release-notes script in webmaster-team/cron git repo.
>

> I have just requested webmaster to switch the bookworm build from the
> master branch to the bookworm branch [1]. After that request gets merged
> and deployed, I'd like you to publish your work in the master branch
> such that we can work from there (and see the results too [2]). Because
> in your worked we stopped making notes per architecture, we probably
> need to make further changes to the webmaster archive, but let's first
> build something.

Hey webmaster team,

please consider MR13 in webmaster's cron repo:

https://salsa.debian.org/webmaster-team/cron/-/merge_requests/13


Thanks

[Holger Wansing]

Created a new bug to track the MR
https://salsa.debian.org/webmaster-team/cron/-/merge_requests/13

That is https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053445

[Holger Wansing]

Hi,

Paul Gevers <elb...@debian.org> wrote (Thu, 24 Aug 2023 14:10:41 +0200):
> I have just requested webmaster to switch the bookworm build from the
> master branch to the bookworm branch [1]. After that request gets merged
> and deployed, I'd like you to publish your work in the master branch
> such that we can work from there (and see the results too [2]). Because
> in your worked we stopped making notes per architecture, we probably
> need to make further changes to the webmaster archive, but let's first
> build something.

Time for a status update:
Since the new release-notes itself are now being built on www-master (based
on Sphinx), some changings were needed for the webpage (currently
www.debian.org/releases/testing/releasenotes), because we no longer have
separate release-notes for the different release-archs.

I did that yesterday, let's say as a proposal.

Previously, there was some sort of black magic (or maybe it's perl),
which automatically creates a table with all architectures, languages,
and output formats of the r-n.
Changing this mechanism to leave out the architecture part is out of my
skills, but I managed to copy (and adapt) the logic which is being used in
the debian.org/doc part of the website, to generate the list of available
languages and formats for the different manuals there.

It looks fine IMO, and it also works. However new languages are not
displayed automatically, so compared to the old mechanism there might
be some handwork needed at some point (but rare I guess).


@webmaster, @release-team, @ddp-team: what do you think? Would this
proposal be acceptable to you for the new release-notes (trixie and later)?

[Holger Wansing]

Hi again,

Holger Wansing <hwan...@mailbox.org> wrote (Mon, 13 Nov 2023 11:19:07 +0100):
> Time for a status update:
> Since the new release-notes itself are now being built on www-master (based
> on Sphinx), some changings were needed for the webpage (currently
> www.debian.org/releases/testing/releasenotes), because we no longer have
> separate release-notes for the different release-archs.
>
> I did that yesterday, let's say as a proposal.
>
> Previously, there was some sort of black magic (or maybe it's perl),
> which automatically creates a table with all architectures, languages,
> and output formats of the r-n.
> Changing this mechanism to leave out the architecture part is out of my
> skills, but I managed to copy (and adapt) the logic which is being used in
> the debian.org/doc part of the website, to generate the list of available
> languages and formats for the different manuals there.
>
> It looks fine IMO, and it also works. However new languages are not
> displayed automatically, so compared to the old mechanism there might
> be some handwork needed at some point (but rare I guess).
>
>
> @webmaster, @release-team, @ddp-team: what do you think? Would this
> proposal be acceptable to you for the new release-notes (trixie and later)?

And since there has been a call for a Debian theme for Sphinx (see
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053549), a proposal
for that can be found at
https://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/release-notes/
(for those, who are uncomfortable with the greenish theme).

[Holger Wansing]

Hi,

Am 24. November 2023 10:50:19 MEZ schrieb Laura Arjona Reina <lar...@debian.org>:
>I've had a quick look at the theme inhttps://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/release-notes/ and looks very nice both in my computer and my phone, and I think it's a good improvement for the current theme. Thank you *very much*.
>
>I don't know which is the better way forward, maybe add a repo for the theme in the ddp-team umbrella, and then file a bug for every documentation manual using Sphinx, suggesting including it?

I used the alabaster theme, which is the default theme in Sphinx, and
set some configuration options in conf.py, to adapt some details. That's all.

So no need to create a new theme IMO.

Just set the appropriate options in the manual, and build it.


Holger


--
Sent from /e/ OS on Fairphone3