Re: [DISCUSS] Alignment of values disabling idleTimeout/loadConditioningInterval between Geode client APIs

[Alberto Gomez]

Thanks for your answer, Darrel.

If the breaking change is not a viable option, how about at least having both 
clients agree on the -1 value (currently -1 is not supported by the native 
client) to mean never idle expire and never load condition respectively?

It is true that they will not agree on the 0 value but at least they would 
agree on -1.

Not sure if this compromise change will really be for the better.

Alberto

From: Darrel Schneider 
Sent: Monday, June 13, 2022 10:03 PM
To: dev@geode.apache.org 
Subject: Re: [DISCUSS] Alignment of values disabling 
idleTimeout/loadConditioningInterval between Geode client APIs

My concern is you are proposing to change the behavior of an existing geode 
feature. I think 0 is currently supported for both these properties in the Java 
client. I would think they cause immediate idle expiration and a very hot load 
conditioning. Your proposal would make 0 mean something very different (never 
idle expire and never load condition).
Also since both of these properties express a time duration, interpreting the 
value 0 as a very short duration is the natural meaning. Treating as an 
infinite duration takes some explanation.
If the native client currently does not support setting these properties to -1 
then you could more safely change it to treat -1 as an infinite duration like 
the Java client does.
So at least both clients would agree on what -1 means.
But they would still disagree on what 0 means. To bring them into agreement you 
need to make a breaking change in either the native client or the java client. 
It might be best just to document this difference. I think it might be a small 
subset of our user base that thinks everything on the native client will be 
consistent with the Java client. Or vice versa. I think most users of one 
client do not even use the other client.


From: Alberto Gomez 
Sent: Monday, June 13, 2022 8:20 AM
To: dev@geode.apache.org 
Subject: [DISCUSS] Alignment of values disabling 
idleTimeout/loadConditioningInterval between Geode client APIs

⚠ External Email

Hi,

According to the documentation of the Geode Java client API, setting -1 for 
idleTimeout in a Pool indicates that connections should never expire:
https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgeode.apache.org%2Freleases%2Flatest%2Fjavadoc%2Forg%2Fapache%2Fgeode%2Fcache%2Fclient%2FPoolFactory.html%23setIdleTimeout-long-&data=05%7C01%7Cdarrel%40vmware.com%7C8d31f0e0512b45f215da08da4d5099a9%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637907305827807591%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=9Lw0czqIngj47SoJM5hJZJxojAcJjqh3OPYescN4Ctg%3D&reserved=0

Nevertheless, according to the documentation of the Geode Native client API, 
setting a duration of std::chrono::milliseconds::zero() for idleTimeout 
indicates that connections should never expire.
https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgeode.apache.org%2Freleases%2Flatest%2Fcppdocs%2Fa00799.html%23ae5fef0b20d95f11399a1fa66f90fbc74&data=05%7C01%7Cdarrel%40vmware.com%7C8d31f0e0512b45f215da08da4d5099a9%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637907305827807591%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=pOzqVhNF1WRj3XYqvM%2BUCcwSTLRc94xaCclBvr5X1t8%3D&reserved=0

A similar discrepancy between the two clients can be observed for the 
loadConditioningInterval setting:

According to the documentation of the Java client API, A value of -1 disables 
load conditioning:
https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgeode.apache.org%2Freleases%2Flatest%2Fjavadoc%2Forg%2Fapache%2Fgeode%2Fcache%2Fclient%2FPoolFactory.html%23setLoadConditioningInterval-int-&data=05%7C01%7Cdarrel%40vmware.com%7C8d31f0e0512b45f215da08da4d5099a9%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637907305827807591%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=bbn6PVstkE9P6ZOcVUZW4%2FJTXrDEIY1UMNJEzq9Oq40%3D&reserved=0

Nevertheless, according to the documentation of the Geode Native client API, 
setting a value of std::chrono::milliseconds::zero() disables load conditioning.
https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgeode.apache.org%2Freleases%2Flatest%2Fcppdocs%2Fa00799.html%23aaa812743d8458017bdbb8afa144c05e7&data=05%7C01%7Cdarrel%40vmware.com%7C8d31f0e0512b45f215da08da4d5099a9%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637907305827807591%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=zUQDeM%2FkwiTjG9WzHp0t3FPqPt48HuFkYvTpLDnSyWk%3D&reserved=0

This discrepancy can create confusion and lead to a misuse of the client APIs 
which can provoke an unexpected behavior in the client.

Geode API clients should be consistent to avoid these typ

Re: [DISCUSS] Alignment of values disabling idleTimeout/loadConditioningInterval between Geode client APIs

[Jacob Barrett]

I have raised this issue a few times. All over our API we are inconsistent with 
time. Either in the use of sentinel values or time units. Given the current API 
and breaking that is not an option until some major release the best thing you 
can do is not use the sentinel values. If you want something to “wait forever” 
set the time to the maximum value, in many cases this is longer than many of us 
will be live, let alone how long the system will stay online or reasonably wait 
for an event.

I would like to see us add new APIs that take strong typed time values for 
things the have timeouts, no time values if the method should wait forever, and 
“try” prefix for things that should try but never wait. Internally I strongly 
suggest we do away with “forever” as a concept and forward all forever blocking 
calls to the timeout version of the method with the max timeout value and unit, 
effectively forever.

-Jake

On Jun 14, 2022, at 3:12 AM, Alberto Gomez 
mailto:alberto.go...@est.tech>> wrote:

⚠ External Email

Thanks for your answer, Darrel.

If the breaking change is not a viable option, how about at least having both 
clients agree on the -1 value (currently -1 is not supported by the native 
client) to mean never idle expire and never load condition respectively?

It is true that they will not agree on the 0 value but at least they would 
agree on -1.

Not sure if this compromise change will really be for the better.

Alberto

From: Darrel Schneider 
mailto:dar...@vmware.com.INVALID>>
Sent: Monday, June 13, 2022 10:03 PM
To: dev@geode.apache.org 
mailto:dev@geode.apache.org>>
Subject: Re: [DISCUSS] Alignment of values disabling 
idleTimeout/loadConditioningInterval between Geode client APIs

My concern is you are proposing to change the behavior of an existing geode 
feature. I think 0 is currently supported for both these properties in the Java 
client. I would think they cause immediate idle expiration and a very hot load 
conditioning. Your proposal would make 0 mean something very different (never 
idle expire and never load condition).
Also since both of these properties express a time duration, interpreting the 
value 0 as a very short duration is the natural meaning. Treating as an 
infinite duration takes some explanation.
If the native client currently does not support setting these properties to -1 
then you could more safely change it to treat -1 as an infinite duration like 
the Java client does.
So at least both clients would agree on what -1 means.
But they would still disagree on what 0 means. To bring them into agreement you 
need to make a breaking change in either the native client or the java client. 
It might be best just to document this difference. I think it might be a small 
subset of our user base that thinks everything on the native client will be 
consistent with the Java client. Or vice versa. I think most users of one 
client do not even use the other client.


From: Alberto Gomez mailto:alberto.go...@est.tech>>
Sent: Monday, June 13, 2022 8:20 AM
To: dev@geode.apache.org 
mailto:dev@geode.apache.org>>
Subject: [DISCUSS] Alignment of values disabling 
idleTimeout/loadConditioningInterval between Geode client APIs

⚠ External Email

Hi,

According to the documentation of the Geode Java client API, setting -1 for 
idleTimeout in a Pool indicates that connections should never expire:
https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgeode.apache.org%2Freleases%2Flatest%2Fjavadoc%2Forg%2Fapache%2Fgeode%2Fcache%2Fclient%2FPoolFactory.html%23setIdleTimeout-long-&data=05%7C01%7Cjabarrett%40vmware.com%7Cea4c426f777a4439a37d08da4dee6b31%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637907983650611670%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=ACne8eenRyT2G1R4uwKO8CfNS3Zh1IYFi5N%2BzhsG0x8%3D&reserved=0

Nevertheless, according to the documentation of the Geode Native client API, 
setting a duration of std::chrono::milliseconds::zero() for idleTimeout 
indicates that connections should never expire.
https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgeode.apache.org%2Freleases%2Flatest%2Fcppdocs%2Fa00799.html%23ae5fef0b20d95f11399a1fa66f90fbc74&data=05%7C01%7Cjabarrett%40vmware.com%7Cea4c426f777a4439a37d08da4dee6b31%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637907983650611670%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=c%2BsEdq6Cp8JGgWf6R8Q8keQXPrUiUS0S0rVtrfczuYc%3D&reserved=0

A similar discrepancy between the two clients can be observed for the 
loadConditioningInterval setting:

According to the documentation of the Java client API, A value of -1 disables 
load conditioning:
https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgeode.apache.org%2Freleases%2Flatest%2Fjavadoc%2Forg

[PROPOSAL] Relocate Geode Docs from code repo to seperate repo

[Dave Barnes]

I'd like to move the doc sources for the Geode User Guide from the code
repo (https://github.com/apache/geode) to a separate geode-docs repo.

The primary reason is to allow docs to cycle at their own rate, rather than
in lock-step with the code. The present arrangement causes problems during
releases, when code is frozen (including doc sources) to prepare a release
candidate. This is exactly the time when critical last-minute doc changes
are needed, but such changes are forbidden due to the code freeze.

I have participated in the Geode project since its inception, and can
confidently state that this conflict arises with nearly every Geode
release. Setting up the docs in a separate repo would alleviate this
regularly-recurring, counter-intuitive situation.

Of note: The docs directories and toolset are almost entirely independent
of directories and tools needed for code development and release, so
removal of the doc sources from the Geode code repo should be painless for
developers.

Observations and opinions welcome...

Dave Barnes

Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo

[Jacob Barrett]

I don’t see any downsides to this approach. We already do this for other assets 
like examples, native, site, and benchmarks.

> On Jun 14, 2022, at 12:03 PM, Dave Barnes  wrote:
> 
> ⚠ External Email
> 
> I'd like to move the doc sources for the Geode User Guide from the code
> repo 
> (https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Cjabarrett%40vmware.com%7C79019270b63a4ee130ba08da4e3a2c77%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908309002941176%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=YMlTGuvk%2FU1bbW7%2F60bhMcO09PKcE3Tb2ew3ymlKySw%3D&reserved=0)
>  to a separate geode-docs repo.
> 
> The primary reason is to allow docs to cycle at their own rate, rather than
> in lock-step with the code. The present arrangement causes problems during
> releases, when code is frozen (including doc sources) to prepare a release
> candidate. This is exactly the time when critical last-minute doc changes
> are needed, but such changes are forbidden due to the code freeze.
> 
> I have participated in the Geode project since its inception, and can
> confidently state that this conflict arises with nearly every Geode
> release. Setting up the docs in a separate repo would alleviate this
> regularly-recurring, counter-intuitive situation.
> 
> Of note: The docs directories and toolset are almost entirely independent
> of directories and tools needed for code development and release, so
> removal of the doc sources from the Geode code repo should be painless for
> developers.
> 
> Observations and opinions welcome...
> 
> Dave Barnes
> 
> 
> 
> ⚠ External Email: This email originated from outside of the organization. Do 
> not click links or open attachments unless you recognize the sender.

Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo

[John Blum]

Personally, I believe doc is a critical component to any software project, 
especially a project like Apache Geode, and so, is the project really “complete 
“(or should thee codebase  really be frozen during a release) if the doc is not 
done or consistent yet?

Having the doc be part of the source allows the doc to be (theoretically) 
in-sync with the codebase as it evolves, as it should be. On the other hand, 
with a separate repo, it does allow corrections or other alterations to be made 
at the risk of growing inconsistency, which is a huge impediment IMO. In 
Asciidoc, doc can even be based on the source in part (e.g. interfaces).

Ideally, I don’t see code and doc being separate or even fundamentally 
different.

This sounds more like a process problem and a workaround to a broken process, 
to me.

$0.02
-John


From: Dave Barnes 
Date: Tuesday, June 14, 2022 at 12:15 PM
To: dev@geode.apache.org 
Subject: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
⚠ External Email

I'd like to move the doc sources for the Geode User Guide from the code
repo 
(https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Cjblum%40vmware.com%7Cb6ae14ef841e416fb22208da4e3a2bb4%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908308999514633%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=vWegMzha9uIc8JMMAYhgxU20V9beAoSbAFOK5aORAfc%3D&reserved=0)
 to a separate geode-docs repo.

The primary reason is to allow docs to cycle at their own rate, rather than
in lock-step with the code. The present arrangement causes problems during
releases, when code is frozen (including doc sources) to prepare a release
candidate. This is exactly the time when critical last-minute doc changes
are needed, but such changes are forbidden due to the code freeze.

I have participated in the Geode project since its inception, and can
confidently state that this conflict arises with nearly every Geode
release. Setting up the docs in a separate repo would alleviate this
regularly-recurring, counter-intuitive situation.

Of note: The docs directories and toolset are almost entirely independent
of directories and tools needed for code development and release, so
removal of the doc sources from the Geode code repo should be painless for
developers.

Observations and opinions welcome...

Dave Barnes



⚠ External Email: This email originated from outside of the organization. Do 
not click links or open attachments unless you recognize the sender.

Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo

[Dave Barnes]

John,
Thanks for acknowledging that docs are just as important as code!  As a
career tech-writer, the "docs=code" model appeals to me.
I get what you're saying, and have worked in environments where release
managers have enforced such constraints.
In this vein, the Geode code is well-supplied with embedded Javadoc
comments that behave exactly as you describe, providing a reference that is
updated as the code is updated.
The difference with a user guide (as opposed to reference material), is
that examples and usage guidelines can be finalized only AFTER the code,
with all its version numbers, naming conventions, etc, are in place.
Delaying code freeze until docs are complete, in my experience, engenders
feature-creep and introduces delays, often resulting in compromises that
allow the release to go out with mis-matched docs. IMO, a separate
user-guide repo promotes a better and more timely match-up between the
software and the user guide.


On Tue, Jun 14, 2022 at 1:15 PM John Blum  wrote:

> Personally, I believe doc is a critical component to any software project,
> especially a project like Apache Geode, and so, is the project really
> “complete “(or should thee codebase  really be frozen during a release) if
> the doc is not done or consistent yet?
>
> Having the doc be part of the source allows the doc to be (theoretically)
> in-sync with the codebase as it evolves, as it should be. On the other
> hand, with a separate repo, it does allow corrections or other alterations
> to be made at the risk of growing inconsistency, which is a huge impediment
> IMO. In Asciidoc, doc can even be based on the source in part (e.g.
> interfaces).
>
> Ideally, I don’t see code and doc being separate or even fundamentally
> different.
>
> This sounds more like a process problem and a workaround to a broken
> process, to me.
>
> $0.02
> -John
>
>
> From: Dave Barnes 
> Date: Tuesday, June 14, 2022 at 12:15 PM
> To: dev@geode.apache.org 
> Subject: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
> ⚠ External Email
>
> I'd like to move the doc sources for the Geode User Guide from the code
> repo (
> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Cjblum%40vmware.com%7Cb6ae14ef841e416fb22208da4e3a2bb4%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908308999514633%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=vWegMzha9uIc8JMMAYhgxU20V9beAoSbAFOK5aORAfc%3D&reserved=0)
> to a separate geode-docs repo.
>
> The primary reason is to allow docs to cycle at their own rate, rather than
> in lock-step with the code. The present arrangement causes problems during
> releases, when code is frozen (including doc sources) to prepare a release
> candidate. This is exactly the time when critical last-minute doc changes
> are needed, but such changes are forbidden due to the code freeze.
>
> I have participated in the Geode project since its inception, and can
> confidently state that this conflict arises with nearly every Geode
> release. Setting up the docs in a separate repo would alleviate this
> regularly-recurring, counter-intuitive situation.
>
> Of note: The docs directories and toolset are almost entirely independent
> of directories and tools needed for code development and release, so
> removal of the doc sources from the Geode code repo should be painless for
> developers.
>
> Observations and opinions welcome...
>
> Dave Barnes
>
> 
>
> ⚠ External Email: This email originated from outside of the organization.
> Do not click links or open attachments unless you recognize the sender.
>

Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo

[Udo Kohlmeyer]

Hi there Dave,

I can understand the frustration that you face. I think the freezing of the 
code is different to that of the docs. I think each project member would agree 
if I stated that changes to the docs on ANY branch should be allowed regardless 
of where in the process of the release the project finds itself. (within common 
sense reasoning of course 😉 )

I am however interested in how we would ensure that the docs repo and the code 
repo, stay “in-sync”? Would we raise JIRA’s (Github issues) with the repo to 
make sure that we don’t miss documenting features or changes? We already suffer 
the problem where feature/changes are made and merged without sufficient docs 
changes. It feels like moving docs to their own repo would move a existing 
problem further away.

I understand that moving the docs to another repo, would enable some form of 
autonomy, but I believe that John might have a point, this feels very much like 
a process problem.

Would it help, if docs have a “special pass” that allows doc modifications to 
happen at any point on any branch, if the changes made relate to actual changes 
that have been completed on the branch? (to avoid docs changes that are out of 
sequence with the deliverable)

--Udo

From: Dave Barnes 
Date: Wednesday, June 15, 2022 at 8:11 AM
To: jb...@vmware.com.invalid 
Cc: dev@geode.apache.org 
Subject: Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
⚠ External Email

John,
Thanks for acknowledging that docs are just as important as code!  As a
career tech-writer, the "docs=code" model appeals to me.
I get what you're saying, and have worked in environments where release
managers have enforced such constraints.
In this vein, the Geode code is well-supplied with embedded Javadoc
comments that behave exactly as you describe, providing a reference that is
updated as the code is updated.
The difference with a user guide (as opposed to reference material), is
that examples and usage guidelines can be finalized only AFTER the code,
with all its version numbers, naming conventions, etc, are in place.
Delaying code freeze until docs are complete, in my experience, engenders
feature-creep and introduces delays, often resulting in compromises that
allow the release to go out with mis-matched docs. IMO, a separate
user-guide repo promotes a better and more timely match-up between the
software and the user guide.


On Tue, Jun 14, 2022 at 1:15 PM John Blum  wrote:

> Personally, I believe doc is a critical component to any software project,
> especially a project like Apache Geode, and so, is the project really
> “complete “(or should thee codebase  really be frozen during a release) if
> the doc is not done or consistent yet?
>
> Having the doc be part of the source allows the doc to be (theoretically)
> in-sync with the codebase as it evolves, as it should be. On the other
> hand, with a separate repo, it does allow corrections or other alterations
> to be made at the risk of growing inconsistency, which is a huge impediment
> IMO. In Asciidoc, doc can even be based on the source in part (e.g.
> interfaces).
>
> Ideally, I don’t see code and doc being separate or even fundamentally
> different.
>
> This sounds more like a process problem and a workaround to a broken
> process, to me.
>
> $0.02
> -John
>
>
> From: Dave Barnes 
> Date: Tuesday, June 14, 2022 at 12:15 PM
> To: dev@geode.apache.org 
> Subject: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
> ⚠ External Email
>
> I'd like to move the doc sources for the Geode User Guide from the code
> repo (
> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Cudo%40vmware.com%7Ce50d39b82ffd499d21d708da4e52c36b%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908414625879240%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=3SKtmt7VI2tBelJRj48xqtW5x%2F9hYNzqFVX9NJe9IC0%3D&reserved=0)
> to a separate geode-docs repo.
>
> The primary reason is to allow docs to cycle at their own rate, rather than
> in lock-step with the code. The present arrangement causes problems during
> releases, when code is frozen (including doc sources) to prepare a release
> candidate. This is exactly the time when critical last-minute doc changes
> are needed, but such changes are forbidden due to the code freeze.
>
> I have participated in the Geode project since its inception, and can
> confidently state that this conflict arises with nearly every Geode
> release. Setting up the docs in a separate repo would alleviate this
> regularly-recurring, counter-intuitive situation.
>
> Of note: The docs directories and toolset are almost entirely independent
> of directories and tools needed for code development and release, so
> removal of the doc sources from the Geode code repo should be painless for
> developers.
>
> Observations and opinions welcome...
>
> Dave Barnes
>
> 

Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo

[Alberto Gomez]

Hi,

I agree with Udo and John that having the docs and the code in the same repo 
really helps to have both in-sync. Therefore, I would not separate them in 
different repos.

I'd rather see a change in the process to overcome the difficulties faced with 
the documentation after the code is frozen.

Alberto

From: Udo Kohlmeyer 
Sent: Wednesday, June 15, 2022 5:05 AM
To: dev@geode.apache.org 
Subject: Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo

Hi there Dave,

I can understand the frustration that you face. I think the freezing of the 
code is different to that of the docs. I think each project member would agree 
if I stated that changes to the docs on ANY branch should be allowed regardless 
of where in the process of the release the project finds itself. (within common 
sense reasoning of course 😉 )

I am however interested in how we would ensure that the docs repo and the code 
repo, stay “in-sync”? Would we raise JIRA’s (Github issues) with the repo to 
make sure that we don’t miss documenting features or changes? We already suffer 
the problem where feature/changes are made and merged without sufficient docs 
changes. It feels like moving docs to their own repo would move a existing 
problem further away.

I understand that moving the docs to another repo, would enable some form of 
autonomy, but I believe that John might have a point, this feels very much like 
a process problem.

Would it help, if docs have a “special pass” that allows doc modifications to 
happen at any point on any branch, if the changes made relate to actual changes 
that have been completed on the branch? (to avoid docs changes that are out of 
sequence with the deliverable)

--Udo

From: Dave Barnes 
Date: Wednesday, June 15, 2022 at 8:11 AM
To: jb...@vmware.com.invalid 
Cc: dev@geode.apache.org 
Subject: Re: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
⚠ External Email

John,
Thanks for acknowledging that docs are just as important as code!  As a
career tech-writer, the "docs=code" model appeals to me.
I get what you're saying, and have worked in environments where release
managers have enforced such constraints.
In this vein, the Geode code is well-supplied with embedded Javadoc
comments that behave exactly as you describe, providing a reference that is
updated as the code is updated.
The difference with a user guide (as opposed to reference material), is
that examples and usage guidelines can be finalized only AFTER the code,
with all its version numbers, naming conventions, etc, are in place.
Delaying code freeze until docs are complete, in my experience, engenders
feature-creep and introduces delays, often resulting in compromises that
allow the release to go out with mis-matched docs. IMO, a separate
user-guide repo promotes a better and more timely match-up between the
software and the user guide.


On Tue, Jun 14, 2022 at 1:15 PM John Blum  wrote:

> Personally, I believe doc is a critical component to any software project,
> especially a project like Apache Geode, and so, is the project really
> “complete “(or should thee codebase  really be frozen during a release) if
> the doc is not done or consistent yet?
>
> Having the doc be part of the source allows the doc to be (theoretically)
> in-sync with the codebase as it evolves, as it should be. On the other
> hand, with a separate repo, it does allow corrections or other alterations
> to be made at the risk of growing inconsistency, which is a huge impediment
> IMO. In Asciidoc, doc can even be based on the source in part (e.g.
> interfaces).
>
> Ideally, I don’t see code and doc being separate or even fundamentally
> different.
>
> This sounds more like a process problem and a workaround to a broken
> process, to me.
>
> $0.02
> -John
>
>
> From: Dave Barnes 
> Date: Tuesday, June 14, 2022 at 12:15 PM
> To: dev@geode.apache.org 
> Subject: [PROPOSAL] Relocate Geode Docs from code repo to seperate repo
> ⚠ External Email
>
> I'd like to move the doc sources for the Geode User Guide from the code
> repo (
> https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fgeode&data=05%7C01%7Cudo%40vmware.com%7Ce50d39b82ffd499d21d708da4e52c36b%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637908414625879240%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=3SKtmt7VI2tBelJRj48xqtW5x%2F9hYNzqFVX9NJe9IC0%3D&reserved=0)
> to a separate geode-docs repo.
>
> The primary reason is to allow docs to cycle at their own rate, rather than
> in lock-step with the code. The present arrangement causes problems during
> releases, when code is frozen (including doc sources) to prepare a release
> candidate. This is exactly the time when critical last-minute doc changes
> are needed, but such changes are forbidden due to the code freeze.
>
> I have participated in the Geode project since its inception, and can
> confidently state