[NEW] Create a dedicated “valkey‑experiments” repo for community tools, benchmarks & samples

[vitarb]

I propose creating a dedicated GitHub repository—valkey-experiments—to house experimental tools, performance benchmarks, agentic integration demos, and one-off utilities related to the Valkey ecosystem. This separate space will enable contributors to iterate quickly on non-core ideas (e.g. MCP server usage samples, LangChain agents, benchmarks, etc.) without bloating the main Valkey repository. Each contribution would live under a structured top-level folder (e.g. benchmarks/, agents/, scripts/) with its own README, status label (alpha/beta/archived), and CODEOWNERS. All experiments must be clearly scoped and self-contained.

To ensure quality and avoid entropy, the repo will include GitHub Actions workflows for basic build/tests, nightly rot-checks, stale experiment tagging, and dependency audits. We’ll define a lightweight RFC process for accepting new tools and enforce boundaries: no code in valkey-experiments should be required by core at build or runtime. By maintaining a clean separation between production and experimental efforts, we’ll encourage innovation while preserving the integrity of the core Valkey project.

[stockholmux]

I have a few of concerns about what's being proposed:

1. If this is a single repo, they could get unmanageable quickly since each example ('experiment' in your description) would be part of the tree. If it scales to 100 examples, that's going to get to be very large and unwieldy. I've seen these organized as each example being a branch (works better than you might imagine) or having it's own github organization.
2. I have concerns about the maintenance. If these are full-fledged projects with their own dependencies, keeping those up-to-date could be a monster. Having unmaintained code sitting out there isn't a very good developer experience.
3. I'd like some guard rails on what would be accepted into this project. Does it need to be an end-to-end example or can it just be a snippets? What if it's very tangential to Valkey? What if someone contributes something that is insecure? What if they use deprecated commands? (I don't need answers to these questions directly, I would like something that crisply defines what should go in this repo)
4. I'm not wild about this begin called 'experiments' it feels like a samples or examples repository instead of something experimental.

[vitarb]

I agree, we should do our best to prevent this from turning into a graveyard, but I think we can achieve that with a set of deliberate checks and retention policy.

Structure

• Every addition lives in a top‑level folder such as benchmarks/…, samples/…, or labs/….
• Each folder carries its own README, CODEOWNERS, and a lightweight make test (or equivalent) so CI can run it in isolation.
• When something is no longer maintained we move it to archive/…; the root stays clean even if we reach 100+ examples.

Maintenance (commit‑time)

• One CI job per PR and merge runs the folder’s build/tests plus a basic lint/vulnerability scan (golangci‑lint, cargo clippy, npm audit, etc.).
• Dependabot keeps dependencies fresh; no extra workflows needed.
• A stale‑label action fires on commits to main. If a folder sees no commits for 120 days it gets a “stale” label; after 180 days we open a PR to move it to archive/….

What gets in

• A short RFC template for each contribution must outline purpose, Valkey touch‑points, security considerations, and status.
• Snippets are welcome if they clearly demonstrate a Valkey pattern. Tangential, insecure, or deprecated code is rejected in review.
• Anything required by core still belongs in the main valkey repo.

Retention

I suggest we start without a strict retention policy, but later on we can enforce inactivity rules and move code that is either inactive for too long or has some issues into inactive sub-tree making sure that primary tools remain clean and are actively maintained.

Name
I used “experiments” as shorthand; happy to switch to valkey-samples, valkey-labs, or whatever the group prefers. The process above is what matters.

If this leaner model sounds reasonable I’ll fold it into the proposal PR for wider review.

[vitarb]

After a thinking a bit more about it, I think I'm leaning towards sub-dividing this into focused repos under valkey-io.
This will help address the concern of having "everything" repo that can easily turn into a mess.

In combination with strong policies mentioned above, I think this should fundamentally address concerns that @stockholmux voiced above and will provide a clean foundation and ownership model for future experimentation.

[rlunar]

Valkey Community Project Repository Structure

I would like to propose a standardized repository structure and naming convention for Valkey community projects within the existing valkey-io GitHub organization. The proposal establishes clear guidelines for hosting demonstration projects, tooling, and ancillary resources that complement the main Valkey core, modules, and clients.

The proposed structure addresses the growing need for practical, real-world examples that demonstrate Valkey's capabilities across diverse technology stacks. By establishing clear governance, naming conventions, and project structures, this initiative will accelerate developer adoption and reduce the barrier to entry for teams looking to integrate Valkey into their applications.

Proposal

Repository Structure within valkey-io

The proposed approach will utilize the existing valkey-io GitHub organization to host community projects alongside the core Valkey repositories. This approach leverages the established brand recognition and community presence while providing clear organization for different types of projects.

Project Naming Convention

Projects should follow the pattern {category}-{language}-{framework/library}-{use-case} where categories include 1/blog for projects accompanying blog posts and tutorials 2/solution for complete solution implementations for specific business problems 3/tool for utilities and tools for working with Valkey 4/integration for integration examples with third-party systems 5/devops for deployment, monitoring, and operational examples 6/sample for basic demonstration and example projects.

Examples of this naming convention include sample-java-spring-data-integration-cache, solution-python-fastapi-session-management, tool-typescript-performance-benchmarking, integration-go-gin-rate-limiting, devops-docker-compose-monitoring, and blog-php-laravel-queue-backend.

Repository Folder Structure

Each repository should follow a consistent top-level structure.

repository-root/
├── README.md
├── LICENSE
├── CONTRIBUTING.md
├── .github/
│   ├── workflows/
│   └── ISSUE_TEMPLATE/
├── docs/
│   ├── setup.md
│   ├── usage.md
│   └── deployment.md
├── src/
│   └── {language-specific-structure}
├── tests/
├── examples/
└── scripts/
    ├── setup.sh
    └── cleanup.sh

Repository Lifecycle Management

Repositories within the community project structure will follow specific lifecycle management policies to ensure quality and relevance. Blog repositories will be created in an archived state from the beginning, reflecting their nature as static accompaniments to published content. All other repository types will follow an active maintenance cycle where repositories are automatically tagged for archival after 180 days of inactivity and permanently archived after one year of inactivity unless explicitly maintained by community contributors.

All repositories, regardless of category, will require automated security scanning for dependency vulnerabilities. This automation will continuously monitor project dependencies and alert maintainers to security issues, ensuring that community projects maintain high security standards and provide safe examples for developers to follow.

Sample Project Structure: Python FastAPI Cache Demo

Project Name

sample-python-fastapi-cache-demo

This detailed example demonstrates how to structure a Python project using modern tooling and best practices. The FastAPI framework was chosen for its excellent performance characteristics, automatic API documentation generation, and strong typing support. The project showcases Valkey integration for caching using the fastapi-cache package, demonstrating both basic and advanced caching patterns. This example serves as a template for other language implementations and establishes the quality standards expected across all community projects.

Project Structure

The sample project follows a comprehensive structure

sample-python-fastapi-cache-demo/
├── README.md
├── LICENSE
├── pyproject.toml
├── uv.lock
├── .python-version
├── .gitignore
├── .github/
│   └── workflows/
│       └── ci.yml
├── src/
│   └── app/
│       ├── __init__.py
│       ├── main.py
│       ├── config.py
│       ├── models/
│       │   ├── __init__.py
│       │   └── user.py
│       ├── routes/
│       │   ├── __init__.py
│       │   ├── health.py
│       │   └── users.py
│       └── cache/
│           ├── __init__.py
│           └── redis.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_main.py
│   └── test_cache.py
├── docs/
│   ├── setup.md
│   ├── api.md
│   └── deployment.md
├── scripts/
│   ├── dev-setup.sh
│   └── test.sh
└── docker-compose.yml

Python Project Configuration

[project]
name = "sample-python-fastapi-cache-demo"
version = "0.1.0"
description = "FastAPI demonstration using Valkey for caching with fastapi-cache"
authors = [
    {name = "Valkey Community", email = "community@valkey.io"}
]
dependencies = [
    "fastapi>=0.104.0",
    "uvicorn[standard]>=0.24.0",
    "fastapi-cache2[redis]>=0.2.1",
    "valkey-py>=5.0.0",
    "pydantic>=2.5.0",
    "pydantic-settings>=2.1.0",
]
requires-python = ">=3.11"
readme = "README.md"
license = {text = "MIT"}

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-asyncio>=0.21.0",
    "httpx>=0.25.0",
    "black>=23.0.0",
    "isort>=5.12.0",
    "flake8>=6.0.0",
    "mypy>=1.7.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
dev-dependencies = [
    "pytest>=7.4.0",
    "pytest-asyncio>=0.21.0",
    "httpx>=0.25.0",
    "black>=23.0.0",
    "isort>=5.12.0",
    "flake8>=6.0.0",
    "mypy>=1.7.0",
]

[tool.black]
line-length = 88
target-version = ['py311']

[tool.isort]
profile = "black"
line_length = 88

[tool.mypy]
python_version = "3.11"
strict = true

Build system configuration uses hatchling as the build backend, while tool-specific configuration sections define standards for code formatting with black using 88-character line length and Python 3.11 as the target version. Import sorting is configured through isort with black profile compatibility, and mypy is set to strict mode for comprehensive type checking.

Python Best Practices Implementation

Package management utilizes uv for Python version management and dependency resolution, leveraging pyproject.toml for all project configuration while pinning dependencies with uv.lock for reproducible builds. The project structure maintains a separate src directory for application code with clear separation of concerns through dedicated modules and comprehensive test coverage in the tests directory.

Code quality is ensured through type hints throughout the codebase, linting with flake8 and formatting with black, and pre-commit hooks for code quality enforcement. Documentation standards include inline code documentation, API documentation leveraging FastAPI's automatic OpenAPI generation, recorded architecture decisions, and performance considerations.

Implementation Guidelines

Repository Standards

The implementation guidelines establish minimum quality standards that all repositories in the organization must meet. These standards ensure consistency across projects, making it easier for developers to navigate between different language examples and understand common patterns. The guidelines also facilitate community contributions by providing clear expectations for code quality, documentation, and project structure.

README requirements include clear project description and use case explanation, comprehensive prerequisites and dependencies listing, step-by-step setup instructions that are easy to follow, usage examples with practical code snippets, deployment instructions for various environments, and contributing guidelines that encourage community participation.

Code quality standards mandate language-specific linting and formatting tools, comprehensive test coverage with a minimum threshold of 80%, type safety implementation where applicable, and adherence to security best practices. Documentation requirements encompass inline code documentation for maintainability, API documentation where relevant, recorded architecture decisions for future reference, and performance considerations for production deployment.

CI/CD Pipeline Requirements

Each repository must include automated testing across multiple language versions to ensure compatibility, code quality checks including linting, formatting, and type checking, security vulnerability scanning to identify potential issues in dependencies, dependency update automation to maintain current versions, and documentation generation and deployment for easy access to project information.

[madolson]

1. Core team meeting. Directionally aligned, @PingXie will take a look at the proposal offline.