ISPN-14082: Document cache naming character limits

[dfitzmau]

JIRA: https://issues.redhat.com/browse/ISPN-14082

Needs backport to 13.0.

[dfitzmau]

Backport label applied, but updates for 13.0 require less content.

[dfitzmau]

Hi @jabolina .

I have written a draft note or notes for the cache name/file name character limit issue.

I've lumped two notes into one for the purposes of a preliminary review.

I'm suggesting to add the cache name restriction to various cache type sectons outlined in the Infinispan caches guide, such as Local caches.

I'm suggesting to add the file name restriction to a file-specific section in the Infinispan caches guide, such as File-based cache stores.

WDYT?

[jabolina]

@dfitzmau Only a minor thing about the text, but looking good. Next week I'll take a look about the location we can add these. If we have a doc dedicated to configuration would be the best place I think.

[dfitzmau]

Thanks!

Yeah I was thinking the Configuring caches document. Notes might need to go into a few sections as different cache types and templates exist in the doc.

Maybe I could add a note at the beginning of a document chapter, such as Infinispan caches.

[jabolina]

Nice, I think that is the place for us to add this. Adding a waning note in the beginning of section 3..

[dfitzmau]

Nice, I think that is the place for us to add this. Adding a waning note in the beginning of section 3..

Thanks. I moved the important notes to the start of section 1 and section 3.

[jabolina]

Just a small change. And two things, I think it would be nice to have to something saying that shorter names are preferable, something in those lines. And we can add this to only one of the files to avoid duplicating, whichever one you prefer is good to me.

[dfitzmau]

Just a small change. And two things, I think it would be nice to have to something saying that shorter names are preferable, something in those lines. And we can add this to only one of the files to avoid duplicating, whichever one you prefer is good to me.

Thanks, @jabolina . I added another sentence to each admonition to state to keep names short. Please let me know your thoughts.

[jabolina]

LGTM. @dvagnero if you could take a look too, please.

[domiborges]

Hi, sorry for the delay. I think this content fits in the documentation/src/main/asciidoc/stories/assembly_cache_configuration.adoc (chapter 3). I think that's where users will look for such information.
The documentation/src/main/asciidoc/stories/assembly_cache_modes.adoc (chapter 1) summarizes use cases.
These two assemblies are both in the same guide and aren't shared in other guides so I'd suggest removing it from chapter 1. WDYT @dfitzmau ?

[dfitzmau]

Hi, sorry for the delay. I think this content fits in the documentation/src/main/asciidoc/stories/assembly_cache_configuration.adoc (chapter 3). I think that's where users will look for such information. The documentation/src/main/asciidoc/stories/assembly_cache_modes.adoc (chapter 1) summarizes use cases. These two assemblies are both in the same guide and aren't shared in other guides so I'd suggest removing it from chapter 1. WDYT @dfitzmau ?

HI @dvagnero . I wanted to put the notes in Chapter 1, so the notes display earlier in the guide to grab the user's attention.

I have removed the notes from chapter ; they now only display in Chapter 3. Please let me know if this is good.

[dfitzmau]

Hi, sorry for the delay. I think this content fits in the documentation/src/main/asciidoc/stories/assembly_cache_configuration.adoc (chapter 3). I think that's where users will look for such information. The documentation/src/main/asciidoc/stories/assembly_cache_modes.adoc (chapter 1) summarizes use cases. These two assemblies are both in the same guide and aren't shared in other guides so I'd suggest removing it from chapter 1. WDYT @dfitzmau ?

HI @dvagnero . I wanted to put the notes in Chapter 1, so the notes display earlier in the guide to grab the user's attention.

I have removed the notes from chapter ; they now only display in Chapter 3. Please let me know if this is good.

Hi @dvagnero . Just a gentle reminder on the above.

[domiborges]

HI @dfitzmau seems like you removed the content from chapter 3 instead.

[domiborges]

Why did you add these empty lines inside the admonitions?

[dfitzmau]

From my experience on other projects, I do this to indicate paragraphs. Might I ask the impact of having blank lines? Do things break?

[domiborges]

What is the maximum filename length? Can the docs be more specific?

[dfitzmau]

Not possible to define, because this can vary depending on what an admin sets for a filename. We need to be vague here, because its outside our control.

[dfitzmau]

HI @dfitzmau seems like you removed the content from chapter 3 instead.

Hi, sorry for the delay. I think this content fits in the documentation/src/main/asciidoc/stories/assembly_cache_configuration.adoc (chapter 3). I think that's where users will look for such information.
The documentation/src/main/asciidoc/stories/assembly_cache_modes.adoc (chapter 1) summarizes use cases.
These two assemblies are both in the same guide and aren't shared in other guides so I'd suggest removing it from chapter 1.

Hi @dvagnero . I'm really confused? You requested that I move content to Chapter 3?

HI @dfitzmau seems like you removed the content from chapter 3 instead.

OK. Might I ask why the notes would sit better in Chapter 3? Chapter 1 to me seems like a better introductory chapter for providing an overview of Infinispan caches.

[domiborges]

@dfitzmau I think I stated it above... Chapter 1 is about Infinispan use cases so adding this note there doesn't make much sense. Chapter 3 is about cache configuration and includes configuration examples with cache names https://infinispan.org/docs/stable/titles/configuring/configuring.html#cache-configuration_cache-configuration

[dfitzmau]

@dfitzmau I think I stated it above... Chapter 1 is about Infinispan use cases so adding this note there doesn't make much sense. Chapter 3 is about cache configuration and includes configuration examples with cache names https://infinispan.org/docs/stable/titles/configuring/configuring.html#cache-configuration_cache-configuration

OK. Updated and added to the section you specified. You OK to approve the PR?

[dfitzmau]

@dfitzmau I think I stated it above... Chapter 1 is about Infinispan use cases so adding this note there doesn't make much sense. Chapter 3 is about cache configuration and includes configuration examples with cache names https://infinispan.org/docs/stable/titles/configuring/configuring.html#cache-configuration_cache-configuration

OK. Updated and added to the section you specified. You OK to approve the PR?

Thanks, @dvagnero . Can I merge this PR? Or do I need an additional reviewer? I understand that QE come into the equation post-merge of the PR.

[domiborges]

@dfitzmau there is the 14 release in progress. Check with the team please

[dfitzmau]

@dfitzmau there is the 14 release in progress. Check with the team please

Sorry I do not understand. When you say team as in docs team or the wider DG team?