Add upstream module documentation and BCR tracking template

[Copilot]

Provides structured process for upstreaming bazel-registry modules (.envoy suffixed versions) to source repos and Bazel Central Registry. Reduces envoy-specific patches by documenting configurable patterns over hardcoding.

Issue Template: .github/ISSUE_TEMPLATE/upstream-module.yml

GitHub issue form for tracking module upstreaming with fields for:

• Module name/version, BCR/source status dropdowns
• Patches/overlays inventory
• Task checklist (compare patches → upstream to source → PR to BCR → switch envoy)
• Links to parent tracking issue Track upstreaming of Envoy Bazel Registry modules to BCR and source repos #3524

Documentation: bazel-registry/README.md

Upstreaming philosophy - Favor generic, configurable changes:

# Bad (hardcoded)
deps = ["@envoy//bazel:boringcrypto"]

# Good (configurable)
deps = select({
    ":use_system_crypto": [],
    "//conditions:default": ["@boringssl//:crypto"],
})

3-stage workflow: source repo (MODULE.bazel + generic fixes) → BCR (once source supports Bazel) → envoy switch (toolshed module retained)

Scenario matrix: Actions for BCR exact match, needs patches, missing module, missing MODULE.bazel

Module structure: Documents modules/<name>/<version>.envoy/ layout with patches/overlays

Checklist: BCR lookup, source MODULE.bazel check, issue creation, upstreaming path

Original prompt

Summary

Add documentation and an issue template to guide the process of upstreaming modules from the bazel-registry/ to Bazel Central Registry (BCR) and source repos.

Background

The bazel-registry/modules/ directory contains Bazel modules with .envoy suffixed versions. The goal is to upstream these to:

1. Source repos - Add MODULE.bazel, Bazel build support, and generic bug fixes
2. Bazel Central Registry (BCR) - Once source has clean Bazel support

Key principles:

• Upstream everything possible to source repos in a generic/configurable way
• Avoid envoy-specific hardcoded paths
• Make dependencies configurable rather than forking
• Toolshed mods stay (immutable, suffixed for disambiguation)

Files to Create

1. Issue Template: .github/ISSUE_TEMPLATE/upstream-module.yml

name: Upstream Module to BCR
description: Track upstreaming a bazel-registry module to Bazel Central Registry
labels: ["upstream:BCR", "dependencies"]
body:
  - type: input
    id: module-name
    attributes:
      label: Module Name
      placeholder: e.g., grpc
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Toolshed Version
      placeholder: e.g., 1.76.0.bcr.1.envoy
    validations:
      required: true
  - type: dropdown
    id: bcr-status
    attributes:
      label: BCR Status
      options:
        - "✅ Exists - update/compare needed"
        - "❌ Not present - new module needed"
        - "❌ Not present - blocked upstream"
    validations:
      required: true
  - type: dropdown
    id: source-status
    attributes:
      label: Source Repo MODULE.bazel
      options:
        - "✅ Has MODULE.bazel"
        - "❌ Needs MODULE.bazel (overlay)"
    validations:
      required: true
  - type: textarea
    id: source-repo
    attributes:
      label: Source Repository
      description: Link to the upstream source repository
      placeholder: e.g., https://github.com/google/cel-cpp
  - type: textarea
    id: patches
    attributes:
      label: Patches/Overlays Applied
      description: List any patches or overlays in the toolshed version
      placeholder: |
        - `module.patch` - description of what it fixes
        - overlay/BUILD.bazel - custom build file
  - type: checkboxes
    id: tasks
    attributes:
      label: Tasks
      options:
        - label: Compare toolshed patches/overlays with upstream
        - label: "Upstream to source repo: Add MODULE.bazel / Bazel build support"
        - label: "Upstream to source repo: Upstream bug fixes (generic, not envoy-specific)"
        - label: "Upstream to source repo: Make hardcoded deps configurable"
        - label: PR to BCR (new module or update)
        - label: Update envoy to use BCR version
  - type: textarea
    id: notes
    attributes:
      label: Notes
      description: Blockers, dependencies, links to upstream issues/PRs
  - type: input
    id: parent-issue
    attributes:
      label: Parent Tracking Issue
      description: Link to the parent tracking issue
      value: "#3524"

2. README: bazel-registry/README.md

Create a comprehensive README with:

Upstreaming Philosophy

Goal: Minimize envoy-specific patches by upstreaming to source repos first.

Type	Example	Approach
Bazel support	MODULE.bazel, BUILD.bazel	Add as first-class build option
Bug fixes	Null pointer checks, compiler compat	Generic fix, not envoy-specific
Configurability	Feature flags, build options	Make configurable, not hardcoded
Platform support	Cross-compile, toolchain fixes	Benefit all users

Avoid:

• ❌ Hardcoding envoy-specific paths (e.g., @envoy//bazel:foo)
• ❌ Patches that only work for envoy's build setup
• ❌ Forking when configuration would suffice

Good vs Bad Example:

Bad (hardcoded):

deps = ["@envoy//bazel:boringcrypto"]

Good (configurable):

deps = select({
    ":use_system_crypto": [],
    "//conditions:default": ["@boringssl//:crypto"],
})

Upstreaming Workflow

┌─────────────────────────────────────────────────────────┐
│  1. UPSTREAM TO SOURCE REPO                             │
│     - MODULE.bazel / BUILD.bazel                        │
│     - Generic bug fixes                                 │
│     - Configurable options (not hardcoded)              │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  2. UPSTREAM TO BCR                                     │
│     - Once source has clean Bazel support               │
│     - Submit module to Bazel Central Registry           │
│     - Include overlays only if source can't change      │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  3. SWITCH ENVOY TO BCR                        ...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for you](https://github.com/envoyproxy/toolshed/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.

[netlify]

✅ Deploy Preview for nifty-bassi-e26446 ready!

Name	Link
🔨 Latest commit	3896e35
🔍 Latest deploy log	https://app.netlify.com/projects/nifty-bassi-e26446/deploys/696d32a787c0bc0008ba36bb
😎 Deploy Preview	https://deploy-preview-3530--nifty-bassi-e26446.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.