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
Den ons 21 apr. 2021 kl 16:41 skrev Josh Durgin <jdurgin@redhat.com>:
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.
Is there a reason to limit docs only to one latest version? On Wed, Apr 21, 2021, 10:49 AM Janne Johansson <icepic.dz@gmail.com> wrote:
Den ons 21 apr. 2021 kl 16:41 skrev Josh Durgin <jdurgin@redhat.com>:
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@ceph.io To unsubscribe send an email to dev-leave@ceph.io
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.
On 4/21/21 9:00 AM, Anthony D'Atri 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
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.
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 :)
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.
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
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@ceph.io To unsubscribe send an email to dev-leave@ceph.io
-- Loïc Dachary, Artisan Logiciel Libre
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@ceph.io To unsubscribe send an email to dev-leave@ceph.io
On Wed, Apr 21, 2021 at 11:26 AM Josh Durgin <jdurgin@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
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
I get where you’re coming from. Tealistically there are a significant number of people who are — for various reasons — running older releases, and we should not abandon them. Sure, one can to a certain extent select an older release by editing the URL, but this isn’t ubiquitously known. At a recent employer I inherited 15 or so Infernalis clusters. Sometimes upgrading or replacing is feasible, sometimes it isn’t, so from personal experience I favor being sensitive to existing production installations. Granted, over time that might get unwieldy, and if something mentions “The new Kraken release” that can and should be freshened; I made a few updates to that end last year. — aad
participants (6)
-
Anthony D'Atri
-
Janne Johansson
-
Josh Durgin
-
Ken Dreyer
-
Loïc Dachary
-
Sasha Litvak