21 Apr
2021
21 Apr
'21
4:41 p.m.
Hey folks, now that Pacific is out I wanted to bring up docs backports.
Today, docs.ceph.com shows master by default, with an appropriate
warning at the top that it represents a development version.
Since the primary audience of the docs is users, not developers, I
suggest that we switch the default branch to the latest stable, i.e.
pacific, and apply the normal backport process to docs that are
relevant to the latest stable release as well.
To kickstart things, I'll prepare a backport of the existing
doc changes since the pacific release.
What do folks think?
Josh
21 Apr
21 Apr
5:49 p.m.
Den ons 21 apr. 2021 kl 16:41 skrev Josh Durgin <jdurgin(a)redhat.com>om>:
Hey folks, now that Pacific is out I wanted to bring
up docs backports.
Today, docs.ceph.com shows master by default, with an appropriate
warning at the top that it represents a development version.
Since the primary audience of the docs is users, not developers, I
suggest that we switch the default branch to the latest stable, i.e.
pacific, and apply the normal backport process to docs that are
relevant to the latest stable release as well.
To kickstart things, I'll prepare a backport of the existing
doc changes since the pacific release.
What do folks think?
I like it.
--
May the most significant bit of your life be positive.
5:55 p.m.
Is there a reason to limit docs only to one latest version?
On Wed, Apr 21, 2021, 10:49 AM Janne Johansson <icepic.dz(a)gmail.com> wrote:
Den ons 21 apr. 2021 kl 16:41 skrev Josh Durgin
<jdurgin(a)redhat.com>om>:
Hey folks, now that Pacific is out I wanted to
bring up docs backports.
Today, docs.ceph.com shows master by default, with an appropriate
warning at the top that it represents a development version.
Since the primary audience of the docs is users, not developers, I
suggest that we switch the default branch to the latest stable, i.e.
pacific, and apply the normal backport process to docs that are
relevant to the latest stable release as well.
To kickstart things, I'll prepare a backport of the existing
doc changes since the pacific release.
What do folks think?
I like it.
--
May the most significant bit of your life be positive.
_______________________________________________
Dev mailing list -- dev(a)ceph.io
To unsubscribe send an email to dev-leave(a)ceph.io
6 p.m.
> Hey folks, now that Pacific is out I wanted to
bring up docs backports.
> Today, docs.ceph.com shows master by default, with an appropriate
> warning at the top that it represents a development version.
>
> Since the primary audience of the docs is users, not developers, I
> suggest that we switch the default branch to the latest stable, i.e.
> pacific
Agree.
> and apply the normal backport process to docs
that are
> relevant to the latest stable release as well.
As with any backport, we’ll of course want to be careful that docs changes to master are
appropriate for the stable release. Do you and/or Zac envision backporting as a
fundamental part of docs contributions? If so that will complicate the docs workflow a
bit and will itself need some specific documentation.
Is there a reason to limit docs only to one latest
version?
Perhaps one has to draw the line somewhere? The farther back one goes, the more work it
takes to ensure that a given change is applicable to the release in question. Over time
the overhead and complexity of contributing has disuaded some docs contributors, so I’m
wary of adding friction.
7:13 p.m.
On 4/21/21 9:00 AM, Anthony D'Atri wrote:
I don't see it as a requirement for docs contributors, I think Zac and
developers familiar with backports can help with the backport process.
I'd rather make it easier to contribute to docs, not harder :)
Yes, it's a matter of applying effort where it's most useful.
Newer releases get more backports, and docs changes most easily apply
(in terms of content and cherry-picking difficulty) to more recent
releases. For pacific in particular, there's been significant
restructuring and retheming of the docs that makes backports
prior to that require more manual effort.
Josh
> Hey folks, now that Pacific is out I wanted
to bring up docs backports.
> Today, docs.ceph.com shows master by default, with an appropriate
> warning at the top that it represents a development version.
>
> Since the primary audience of the docs is users, not developers, I
> suggest that we switch the default branch to the latest stable, i.e.
> pacific
Agree.
> and apply the normal backport process to
docs that are
> relevant to the latest stable release as well.
As with any backport, we’ll of course want to be careful that docs changes to master are
appropriate for the stable release. Do you and/or Zac envision backporting as a
fundamental part of docs contributions? If so that will complicate the docs workflow a
bit and will itself need some specific documentation. Is there a
reason to limit docs only to one latest version?
Perhaps one has to draw the line somewhere? The farther back one goes, the more work it
takes to ensure that a given change is applicable to the release in question. Over time
the overhead and complexity of contributing has disuaded some docs contributors, so I’m
wary of adding friction. 
6:57 p.m.
Hi Josh,
This is an excellent idea :+1:. I often switch:
https://docs.ceph.com/en/latest/man/8/rbd/
to
https://docs.ceph.com/en/octopus/man/8/rbd/
to make sure a given option/command exists in the stable release. Another
convenient way to see version specific changes is to embed them in the documentation
itself. For instance
https://docs.python.org/3.9/library/asyncio-task.html#sleeping
"Deprecated since version 3.8, will be removed in version 3.10: The loop
parameter."
But it's a *lot* more work and sometime confusing and ends up cluttering the
documentation.
Cheers
On 21/04/2021 16:41, Josh Durgin wrote:
Hey folks, now that Pacific is out I wanted to bring
up docs backports.
Today, docs.ceph.com shows master by default, with an appropriate
warning at the top that it represents a development version.
Since the primary audience of the docs is users, not developers, I
suggest that we switch the default branch to the latest stable, i.e.
pacific, and apply the normal backport process to docs that are
relevant to the latest stable release as well.
To kickstart things, I'll prepare a backport of the existing
doc changes since the pacific release.
What do folks think?
Josh
_______________________________________________
Dev mailing list -- dev(a)ceph.io
To unsubscribe send an email to dev-leave(a)ceph.io
--
Loïc Dachary, Artisan Logiciel Libre
7:25 p.m.
On 4/21/21 9:57 AM, Loïc Dachary wrote:
to make sure a given option/command exists in the
stable release. Another
convenient way to see version specific changes is to embed them in the documentation
itself. For instance
https://docs.python.org/3.9/library/asyncio-task.html#sleeping
"Deprecated since version 3.8, will be removed in version 3.10: The loop
parameter."
But it's a *lot* more work and sometime confusing and ends up cluttering the
documentation.
Yes, this is a bit orthogonal to me, since it applies more to particular
technical changes rather than changes like improving the wording or
filling in some missing docs.
We do have the version-added directive in sphinx to help with this sort
of indicator, but it is harder to maintain - I just removed some
referencing cuttlefish last week!
Josh
Cheers
On 21/04/2021 16:41, Josh Durgin wrote:
Hey folks, now that Pacific is out I wanted to
bring up docs backports.
Today, docs.ceph.com shows master by default, with an appropriate
warning at the top that it represents a development version.
Since the primary audience of the docs is users, not developers, I
suggest that we switch the default branch to the latest stable, i.e.
pacific, and apply the normal backport process to docs that are
relevant to the latest stable release as well.
To kickstart things, I'll prepare a backport of the existing
doc changes since the pacific release.
What do folks think?
Josh
_______________________________________________
Dev mailing list -- dev(a)ceph.io
To unsubscribe send an email to dev-leave(a)ceph.io
22 Apr
22 Apr
5:57 p.m.
On Wed, Apr 21, 2021 at 11:26 AM Josh Durgin <jdurgin(a)redhat.com> wrote:
We do have the version-added directive in sphinx to
help with this sort
of indicator, but it is harder to maintain - I just removed some
referencing cuttlefish last week!
On this subject, I was reading
https://docs.ceph.com/en/latest/radosgw/multisite/ says "New in
version Jewel." and there's six references to "Kraken".
Are we good with cleaning up all references to EOL versions? The docs
could simply describe the current behavior and avoid mentioning
releases that are not active (defined on
https://docs.ceph.com/en/latest/releases/)
- Ken
7:35 p.m.
We do have the version-added directive in sphinx
to help with this sort
of indicator, but it is harder to maintain - I just removed some
referencing cuttlefish last week!
On this subject, I was reading
https://docs.ceph.com/en/latest/radosgw/multisite/ says "New in
version Jewel." and there's six references to "Kraken".
Are we good with cleaning up all references to EOL versions? The docs
could simply describe the current behavior and avoid mentioning
releases that are not active (defined on
https://docs.ceph.com/en/latest/releases/)
- Ken
1093
days inactive
1094
days old
9 comments
6 participants
participants (6)
-
Anthony D'Atri -
Janne Johansson -
Josh Durgin -
Ken Dreyer -
Loïc Dachary -
Sasha Litvak