Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 49 additions & 3 deletions .github/ISSUE_TEMPLATE/extension.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,22 @@ body:
validations:
required: true

- type: input
id: debian-package-name
attributes:
label: Debian Package Name
description: |
The name of the Debian package in the `main` component (which by
definition complies with the [Debian Free Software Guidelines (DFSG)](https://www.debian.org/social_contract#guidelines)).
The PGDG (PostgreSQL Global Development Group) repository is the recommended
source, but other trusted, auditable Debian repositories are acceptable. Verify availability by running
`apt search <name>` inside a
`ghcr.io/cloudnative-pg/postgresql:<pg_version>-minimal-<distro>` container,
and provide the repository URL if not PGDG.
placeholder: ex. postgresql-<pg-major>-pgvector
validations:
required: true

- type: input
id: website-url
attributes:
Expand Down Expand Up @@ -65,20 +81,50 @@ body:
validations:
required: true

- type: dropdown
id: license-spdx
attributes:
label: Extension License (SPDX identifier)
description: |
Select the SPDX license identifier for the extension. Only licenses on the
[CNCF Allowlist License Policy](https://github.com/cncf/foundation/blob/main/policies-guidance/allowed-third-party-license-policy.md)
are accepted for distribution through this project. If your extension is
licensed under something not listed here, select "Other": Allowlisted
licenses not in this dropdown will be accepted after manual triage;
non-Allowlisted licenses will not be accepted.
options:
- PostgreSQL
- MIT
- Apache-2.0
- BSD-2-Clause
- BSD-3-Clause
- ISC
- Other (verify against the CNCF Allowlist)
validations:
required: true

- type: checkboxes
id: license-check
attributes:
label: License Compliance
description: Please confirm the license of the extension complies with the **allowed licenses** for this project.
description: |
All components in the extension image (the extension itself and any
transitive dependencies) must be covered by a license on the
[CNCF Allowlist License Policy](https://github.com/cncf/foundation/blob/main/policies-guidance/allowed-third-party-license-policy.md).
Extensions that include any non-Allowlisted components will not be accepted.
options:
- label: The extension's license (linked above) complies with the list of allowed licenses.
- label: To the best of my knowledge, the extension and its declared dependencies meet the CNCF Allowlist policy stated above.
required: true

- type: textarea
id: dependent-extensions
attributes:
label: Known Dependent Extensions
description: List any other PostgreSQL extensions that MUST be installed before or alongside this extension (e.g., if this extension requires 'plpgsql' or 'postgis' to be present). If none, please state "None".
description: |
List any other PostgreSQL extensions that must be present for this extension to
function (i.e. extensions that must be created via `CREATE EXTENSION` before this
one). This covers PostgreSQL-level dependencies only; OS-level system library
dependencies are handled separately by the build system. If none, state "None".
placeholder: ex. postgis
validations:
required: true
Expand Down
40 changes: 26 additions & 14 deletions CONTRIBUTING_NEW_EXTENSION.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ setting up your environment to submitting a Pull Request.
Before proposing a change, ensure your local machine is compatible with the
[build stack](BUILD.md).

1. **Fork** the [cloudnative-pg/postgres-extensions-containers](https://github.com/cloudnative-pg/postgres-extensions-containers) repository.
1. **Fork** the [cloudnative-pg/postgres-extensions-containers](https://github.com/cloudnative-pg/postgres-extensions-containers)
repository.
2. **Clone** your fork and enter the directory:
```sh
git clone https://github.com/<your-username>/postgres-extensions-containers.git
Expand All @@ -33,9 +34,12 @@ Before proposing a change, ensure your local machine is compatible with the

To maintain high standards and avoid duplicated effort or architectural
conflicts, every new extension begins with a formal proposal.
During this phase, you must verify that the extension is available in the PGDG
(PostgreSQL Global Development Group) repositories and identify its versioning
logic.
During this phase, you must verify that the extension is available as a
Debian package in the `main` component (which by definition complies with
the [Debian Free Software Guidelines (DFSG)](https://www.debian.org/social_contract#guidelines)),
from a trusted, auditable repository, and identify its versioning logic. The PGDG (PostgreSQL Global Development Group) repository is the
recommended source; other Debian repositories are acceptable provided they meet
the same standards.

### Identifying the Package & Version

Expand Down Expand Up @@ -111,18 +115,23 @@ submit your proposal:

1. Point your browser to ["New Extension Proposal"](https://github.com/cloudnative-pg/postgres-extensions-containers/issues/new/choose).
2. Provide the package name, versioning info, and a link to the upstream source.
3. State the license clearly:
- CNCF-Allowed: licenses on the [CNCF Allowlist](https://github.com/cncf/foundation/blob/main/policies-guidance/allowed-third-party-license-policy.md) (e.g., Apache-2.0, MIT, or PostgreSQL) are generally pre-approved.
- Other Open Source: licenses like FSF-approved (GNU GPL) will be evaluated on a case-by-case basis.
- Redistribution: since we redistribute unmodified software, ensure you
identify where the upstream source code can be found (required for GNU
GPL compliance).
3. State the license clearly. Every component in the extension image must be
covered by a license on the
[CNCF Allowlist](https://github.com/cncf/foundation/blob/main/policies-guidance/allowed-third-party-license-policy.md)
(e.g., Apache-2.0, MIT, PostgreSQL License). CNCF policy requires a formal
exception for any component not covered by the Allowlist; the maintainers
do not intend to file exception requests for new extensions, so only
Allowlisted components will be accepted. This is a governance decision,
not a legal limitation; contributors whose extension cannot meet this
requirement are welcome to adopt the same build tooling and distribute
images independently.

> [!NOTE]
> You do not need to wait for maintainer approval to begin development or
> submit your PR. You are encouraged to proceed immediately; however, please be
> aware that if a fundamental issue (e.g., licensing) is discovered during the
> proposal review, you may need to modify or discard your work.
> In most cases you may begin development before receiving maintainer
> approval. However, if a fundamental problem (e.g., a non-Allowlisted
> license) is discovered during the proposal review, your work will not be
> mergeable. Verify license compliance before investing significant
> development effort.

---

Expand Down Expand Up @@ -289,6 +298,9 @@ Submission Requirements:
that you have the right to submit the code under the project's license.
- **Upstream Target**: Ensure your Pull Request is targeting the `main` branch of
the upstream repository.
- **CODEOWNERS**: The PR must add an entry to the [`CODEOWNERS`](./CODEOWNERS)
file listing the GitHub handles of the component owner(s) for the new
extension folder.

By submitting, you confirm your commitment to maintain this extension on behalf
of the CloudNativePG Community.
60 changes: 43 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,10 @@ integrate seamlessly with the image volume extensions feature in CloudNativePG.
## Supported Extensions

CloudNativePG actively maintains the following third-party extensions, provided
they are maintained by their respective authors, and PostgreSQL Debian Group
(PGDG) packages are available.
they are maintained by their respective authors and distributed as
Debian packages that comply with the Debian Free Software Guidelines (DFSG),
from a trusted, auditable repository
(see [Extension Requirements](#extension-requirements)).

| Extension | Description | Project URL | Maintained by |
| :--- | :--- | :--- | :--- |
Expand All @@ -39,6 +41,12 @@ they are maintained by their respective authors, and PostgreSQL Debian Group
| **[pgvector](pgvector)** | Vector similarity search for PostgreSQL | [github.com/pgvector/pgvector](https://github.com/pgvector/pgvector) | CNPG maintainers |
| **[PostGIS](postgis)** | Geospatial database extension for PostgreSQL | [postgis.net/](https://postgis.net/) | CNPG maintainers |

> [!NOTE]
> PostGIS is licensed under GPL-2.0, which is not on the CNCF Allowlist. It
> predates this policy; the maintainers are filing a CNCF license exception
> for it. PostGIS is not a precedent for accepting further non-Allowlisted
> extensions.

Extensions are provided only for the OS versions already built by the
[`cloudnative-pg/postgres-containers`](https://github.com/cloudnative-pg/postgres-containers) project,
specifically Debian `stable` and `oldstable`.
Expand All @@ -63,31 +71,49 @@ The project adheres to the following frameworks:
When proposing a new extension, the following criteria must be met:

- **Licensing and IP ownership:** We redistribute unmodified third-party
software as container images. We prioritize licenses explicitly allowed by the
[CNCF License Policy](https://github.com/cncf/foundation/blob/main/policies-guidance/allowed-third-party-license-policy.md),
which includes the PostgreSQL License (relevant to this project). Other
open-source licenses, such as FSF-approved licenses (e.g., GNU GPL), will be
considered on a case-by-case basis to ensure compliance with redistribution
requirements.
software as container images. Every component in an extension image must be
covered by a license on the
[CNCF Allowlist License Policy](https://github.com/cncf/foundation/blob/main/policies-guidance/allowed-third-party-license-policy.md),
which includes Apache-2.0, MIT, and the PostgreSQL License. CNCF policy
requires a formal exception for any component not covered by the Allowlist.
Beyond the grandfathered PostGIS case, the maintainers do not intend to file
further exception requests, so only Allowlisted components will be accepted
for new extensions in this project.
This is a governance decision, not a legal limitation; contributors whose
extension cannot meet this requirement are welcome to adopt the same build
tooling and distribute images independently.
- **Structure:** only one extension can be included within an extension folder.
- **Debian Packages:** Extension images must be built using a Debian package
provided by a trusted source like the
[PostgreSQL Global Development Group (PGDG)](https://wiki.postgresql.org/wiki/Apt).
This ensures compatibility with the base images and standard package
management procedures.
- **Debian Packages:** Extension images must be built **exclusively** from
Debian packages in the `main` component (which by definition complies with
the [DFSG](https://www.debian.org/social_contract#guidelines)), sourced from
a trusted, auditable repository.
The [PostgreSQL Global Development Group (PGDG)](https://wiki.postgresql.org/wiki/Apt)
is the recommended source, but other Debian repositories are acceptable
provided they meet the same standards. This is a hard requirement for two
reasons: (a) Debian DEP-5 machine-readable copyright files are the mechanism
used to satisfy attribution obligations: they are copied into
`/licenses/<pkg>/` in the final `FROM scratch` image at build time; (b)
[DFSG](https://www.debian.org/social_contract#guidelines) compliance
guarantees that non-free components have been removed by the package
maintainers, ensuring license hygiene.
- **License inclusion:** all necessary license agreements for the extension and
its dependencies must be included within the extension folder (refer to the
examples in the `pgvector` and `postgis` folders).

See [Adding a New Extension](./CONTRIBUTING_NEW_EXTENSION.md) for the full
workflow on proposing and submitting a new extension.

### Submission Process

1. **Request and commitment:** Open a new issue requesting the extension.
The contributor(s) must agree to become "component owners" and maintainers
for that extension.
2. **Approval:** Once approved by maintainers, the component owner(s) will be
added to the `CODEOWNERS` file for the specific folder.
3. **Submission:** Component owner(s) open a Pull Request (PR) to introduce the
new extension. The PR is reviewed, approved, and merged.
2. **Approval:** Maintainers review the proposal and either approve it or
request changes.
3. **Submission:** Component owner(s) open a Pull Request (PR) to introduce
the new extension. The PR must include an entry in the `CODEOWNERS` file
adding the component owner(s) for the new extension folder. The PR is
reviewed, approved, and merged.
4. **Naming:** The name of the extension is the registry name.

### Removal Policy
Expand Down
Loading