laminas/laminas-cache

Removal of abandoned storage adapter from documentation

boesing opened this issue · 8 comments

boesing commented

Feature Request

Q A
Documentation yes

Summary

With the Technical Steering Committee Meeting in May 2021, we decided to abandon some cache adapters for several reasons.

Components are already archived and thus wont receive any new releases.

The only thing what is missing: Documentation removal of these components.

We can do this with v3 while keeping documentation for v2. This would require us to provide versionized documentation for this component which is actually unavailable. I think I need guidance by @froschdesign or @weierophinney to make that happen.

froschdesign commented

@boesing
If it helps, I'll make the conversion.

boesing commented

@froschdesign Sure, that would help a lot!

froschdesign commented

@boesing
The versioning is only the first step, the structure also needs an update. At the moment I see the following problems:

  • introduction is missing with descriptions for storage, patterns, etc.
  • at the moment, the basic usage page is not included in the navigation
  • available adapters are hidden
  • the adapters page is too long

My suggestions:

  • create an introduction
  • rework the entire quick start page and add it to the navigation
  • create a separate page for each adapter, then they can be listed in the navigation
  • add descriptions for application integrations (laminas-mvc, Mezzio)
  • extend the homepage and add the features of laminas-cache (available adapters, PSR support, etc.)

What do you think?

boesing commented

create a separate page for each adapter, then they can be listed in the navigation

I like this. Having each adapter available as a dedicated navigation entry sounds exactly what we need.
However, I have a few things I really don't like in having all adapters documented in this cache component.
These adapters do have independent versions and thus will need dedicated versions in the documentation starting at some point.

add descriptions for application integrations (laminas-mvc, Mezzio)

Yah, these are lacking currently. Sounds good.

extend the homepage and add the features of laminas-cache (available adapters, PSR support, etc.)

This also sounds reasonable!

Overall, I really like these ideas. Just as mentioned, the one thing that the adapters will start diverge and will need some versionized documentation at some point. What I really don't like when contributing to symfony is to create dedicated PRs in 2 repositories to provide:

a) the feature
b) the documentation

If we start doing this in the laminas-cache component, I see some pain points tho. But thats only my personal view on this. However, if we do this, we have to modify the issue templates in each adapter to mention that for PRs containing features, one has to create a PR to the laminas-cache component as well.

@froschdesign @settermjd Would you guys mind helping me with this? I will try to create some PRs regarding documentation but overall, I am also quite busy with migrating all the packages and provide migration documentation.
Not sure what to focus first - overall documentation or migration + release of v3.0

Do you have any tips for me on how to balance focus for the greater goods? :D

froschdesign commented

What I really don't like when contributing to symfony is to create dedicated PRs in 2 repositories to provide:

a) the feature
b) the documentation

Good point and we must find a solution for this. The current documentation solution MkDocs does not support this feature but we can not change the documentation tool at this point – unfortunately there is no time.

There is an unpopular solution via Git: submodules.

Would you guys mind helping me with this?

Sure!

overall documentation or migration + release of v3.0

Migration + release of v3.0.

(The release must contain a migration guide. Like: https://docs.laminas.dev/laminas-form/v3/migration/v2-to-v3/)

  • ❤️1
froschdesign commented

@boesing

What I really don't like when contributing to symfony is to create dedicated PRs in 2 repositories to provide:

a) the feature
b) the documentation

I tested the "gitsnippet" plugin for MkDocs to include markdown files from a different Git repository:

{{ gitsnippet('git@github.com:laminas/laminas-cache-storage-adapter-filesystem.git', '/docs/book/v1/intro.md', '') }}

The plugin uses GitPython to fetch the content and it supports getting the full content of a file or extracting a section.

boesing commented

Is it also possible to provide a whole navigation tree via gitsnippet?
I would prefer having the possibility to have anything provided by this repository under a dedicated navigation subtree so we can add different documentation here which is all passed automagically to the cache documenation.

So like:

- Storage Adapters
-- Redis (gitsnippet load tree for redis from redis adapter repository)
--- Redis
---- RedisOptions
--- RedisCluster
---- RedisClusterOptions from Ini
---- RedisClusterOptions


Something like this would be preferred without having to add everything manually to the `laminas-cache` repo.
froschdesign commented

Is it also possible to provide a whole navigation tree via gitsnippet?

No, only snippets which can be placed in a file / on a page.
Thank you for the example, which helps to check other options.