--- Begin Message ---
Package: release-notes
Severity: wishlist
Tags: patch
This file's the shortest, and only has two trivial stylistic issues,
but might need some attention to the content.
Index: old-stuff.dbk
===================================================================
--- old-stuff.dbk (revision 11524)
+++ old-stuff.dbk (working copy)
@@ -30,7 +30,8 @@
<title>Checking your sources list</title>
<para>
If any of the lines in your <filename>/etc/apt/sources.list</filename> refer to
-'stable', you are effectively already <quote>using</quote> &releasename;. This
+<quote><literal>stable</literal></quote>,
+you are effectively already <quote>using</quote> &releasename;. This
might not be what you want if you are not ready yet for the upgrade. If
you have already run
<literal>apt-get update</literal>, you can still get back without problems
Replacing the use of "verbatim" single-quotes with the markup normally
used for that function in these release-notes.
In a release or two we might want to turn some or all of these
references to "apt-get" into plain "apt", but here I think it doesn't
much matter.
Another change I'm not sure enough about to have put in the patch:
<para>
Open the file <filename>/etc/apt/sources.list</filename> with your favorite
editor (as <literal>root</literal>) and check all lines beginning with
<literal>deb http:</literal> or <literal>deb ftp:</literal> for a reference to
<quote><literal>stable</literal></quote>. If you find any, change
<literal>stable</literal> to <literal>&oldreleasename;</literal>.
</para>
Maybe this wants a footnote pointing to the no-more-FTP announcement:
"https://lists.debian.org/debian-announce/2017/msg00001.html";. Mind
you, this is assuming that FTP will still technically be usable in
Stretch with secondary mirrors; but do we know if there really are any
that support FTP? If not, instead of a possible footnote it'll want a
definite inline warning to start by switching to HTTP.
For Buster we'll also want to mention at least "deb https:".
Incidentally, the release-notes mention /etc/apt/sources.list plenty
of times but never /etc/apt/sources.list.d/*.list files; and soon
we'll also have the option of deb822-style .sources files - see the
sources.list(5) in stretch. We'll need to come up with a generic term
and use that instead; I'd suggest "APT source-list files".
@@ -59,7 +62,7 @@
Do not change any lines that begin with <literal>deb cdrom:</literal>.
Doing so would invalidate the line and you would have to
run <command>apt-cdrom</command> again. Do not be alarmed if a
- 'cdrom' source line refers to <quote><literal>unstable</literal></quote>.
+ <literal>cdrom:</literal> source line refers to <quote><literal>unstable</literal></quote>.
Although confusing, this is normal.
</para>
</important>
As above.
Then there's another section that may need some updating (but again
I've left it untouched in my patch for now):
<title>Upgrade legacy locales to UTF-8</title>
Most of this has been here since squeeze, and the added examples of
bad consequences were basically "upstream wontfix" even then. These
days the docs say things like "neither dbus-daemon nor systemd
supports environment variables with non-UTF-8 names or values", so
it's not just a matter of GNOME - we should probably replace this
whole section with something more like:
<para>
Using a legacy non-UTF-8 locale has been unsupported by desktops and
other mainstream software projects for a long time. Such locales
should be upgraded by running <command>dpkg-reconfigure
locales</command> and selecting a UTF-8 default. You should also
ensure that users are not overriding the default to use a legacy
locale in their environment.
</para>
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Index: old-stuff.dbk
===================================================================
--- old-stuff.dbk (revision 11524)
+++ old-stuff.dbk (working copy)
@@ -30,7 +30,8 @@
<title>Checking your sources list</title>
<para>
If any of the lines in your <filename>/etc/apt/sources.list</filename> refer to
-'stable', you are effectively already <quote>using</quote> &releasename;. This
+<quote><literal>stable</literal></quote>,
+you are effectively already <quote>using</quote> &releasename;. This
might not be what you want if you are not ready yet for the upgrade. If
you have already run
<literal>apt-get update</literal>, you can still get back without problems
@@ -59,7 +60,7 @@
Do not change any lines that begin with <literal>deb cdrom:</literal>.
Doing so would invalidate the line and you would have to
run <command>apt-cdrom</command> again. Do not be alarmed if a
- 'cdrom' source line refers to <quote><literal>unstable</literal></quote>.
+ <literal>cdrom:</literal> source line refers to <quote><literal>unstable</literal></quote>.
Although confusing, this is normal.
</para>
</important>
--- End Message ---
--- Begin Message ---
Justin B Rye:
> Package: release-notes
> Severity: wishlist
> Tags: patch
>
> This file's the shortest, and only has two trivial stylistic issues,
> but might need some attention to the content.
>
Thanks!
I have applied the patch and also rewritten some of the content based on
your remarks. :)
> [...]
>
> In a release or two we might want to turn some or all of these
> references to "apt-get" into plain "apt", but here I think it doesn't
> much matter.
>
Ack, have left them as-is
> Another change I'm not sure enough about to have put in the patch:
>
> <para>
> Open the file <filename>/etc/apt/sources.list</filename> with your favorite
> editor (as <literal>root</literal>) and check all lines beginning with
> <literal>deb http:</literal> or <literal>deb ftp:</literal> for a reference to
> <quote><literal>stable</literal></quote>. If you find any, change
> <literal>stable</literal> to <literal>&oldreleasename;</literal>.
> </para>
>
> Maybe this wants a footnote pointing to the no-more-FTP announcement:
> "https://lists.debian.org/debian-announce/2017/msg00001.html";. Mind
> you, this is assuming that FTP will still technically be usable in
> Stretch with secondary mirrors; but do we know if there really are any
> that support FTP? If not, instead of a possible footnote it'll want a
> definite inline warning to start by switching to HTTP.
>
I opted for a footnote, text:
<literal>deb ftp:</literal><footnote>
<para>
<ulink
url="https://lists.debian.org/debian-announce/2017/msg00001.html";>Debian
will remove FTP access to all of its official mirrors on
2017-11-01</ulink>. If your sources.list contains a
<literal>debian.org</literal> host, please consider switching to
<ulink url="https://deb.debian.org";>deb.debian.org</ulink>.
This note only applies to mirrors hosted by Debian itself. If you
use a secondary mirror or a third-party repository, then they may
still support FTP access after that date. Please consult with the
operators of these if you are in doubt.
</para>
</footnote>
> For Buster we'll also want to mention at least "deb https:".
>
I added it already along with "tor+" variants.
> Incidentally, the release-notes mention /etc/apt/sources.list plenty
> of times but never /etc/apt/sources.list.d/*.list files; and soon
> we'll also have the option of deb822-style .sources files - see the
> sources.list(5) in stretch. We'll need to come up with a generic term
> and use that instead; I'd suggest "APT source-list files".
>
We should but haven't done it. I am filing a separate bug for that.
> [...]
>
> Then there's another section that may need some updating (but again
> I've left it untouched in my patch for now):
>
> <title>Upgrade legacy locales to UTF-8</title>
>
> [...] We should probably replace this whole section with something more like:
> [...]
>
Done as well. :)
Thanks,
~Niels
--- End Message ---