On Wed, Nov 30, 2022 at 08:25:19AM -0700, David G. Johnston wrote: > On Wed, Nov 30, 2022 at 8:02 AM Bruce Momjian <br...@momjian.us> wrote: > On Wed, Nov 30, 2022 at 07:10:35AM -0700, David G. Johnston wrote: > If everyone agrees this new chapter is helpful, and as helpful to PG 11 > users as PG 16 users, why would we not give users this information in > our docs now? What is the downside? Chapter numbers? Translations? > > Admittedly the policy is more about "we don't expend any effort to write back > branch patches for this kind of material" rather than "we don't do back > patching because it causes problems". But it is an existing policy, applied > consistently through the years, and treating the documentation like a book, > even though it is published in a non-physical medium, is a reasonable > guideline > to follow.
Well, we have not backpatched cosmetic or wording improvements into back branches, usually, though unclear wording has been backpatched because the value is more significant than the disruption. I think we look at doc backpatching on an individual basis, because there are limited risks, unlike code changes. > My desire to get it out in an official release early goes against this policy, > and I'm fine waiting for v16 on that basis. The only reason I'm good with > updating v15 is that I basically consider anything in the first 3 point > releases of a major version to be a "delta" release. Well, yeah, I think the PG 15-16 is kind of an odd approach, though I can see the value of doing that since we could say anyone who cares about these details should be on the most recent major release. I think you are reinforcing my basic approach that doc changes can't have a simple blanket policy, unlike code, because of the limited risks and significan value. > One back-patchable idea to consider would be adding a note at the top of the > page(s) highlighting the fact that said material has been superseded by more > current documentation, with a link. But the idea of changing long-released > (see my delta comment above) material doesn't sit well with me or the policy. Uh, I don't share that concern, as long as it is mentioned in the minor release notes. > I assume this new chapter would be mentioned in the minor release notes. > > We don't do release notes for documentation changes. Uh, I certainly have done it for significant doc improvements in major releases, so I don't see a problem in doing it for minor releases, especially since this information has been needed in our docs for years. What I am basically saying is that "we have always done it that way" is an insufficient reason for me --- we should have some logic for _why_ we have a policy, and I am not seeing that here. This is obviously a bigger issue than this particular patch. -- Bruce Momjian <br...@momjian.us> https://momjian.us EDB https://enterprisedb.com Embrace your flaws. They make you human, rather than perfect, which you will never be.
