mirror of https://github.com/knative/community.git
241 lines
10 KiB
Markdown
241 lines
10 KiB
Markdown
---
|
|
title: "Knative Repository Guidelines"
|
|
linkTitle: "Repository Guidelines"
|
|
weight: 25
|
|
type: "docs"
|
|
aliases:
|
|
- /contributing/repository-guidelines/
|
|
---
|
|
|
|
This document outlines a structure for creating and associating code
|
|
repositories with the Knative project. It also describes how and when
|
|
repositories are removed.
|
|
|
|
## Core Repositories
|
|
|
|
Core repositories are considered core components of Knative. They are utilities,
|
|
tools, applications, or libraries that form or support the foundation of the
|
|
project.
|
|
|
|
Core repositories are all those located under the
|
|
[github.com/knative organization](https://github.com/knative).
|
|
|
|
### Core Repository Requirements
|
|
|
|
- Repository must live under github.com/knative/project-name.
|
|
- Must adopt the Knative Code of Conduct.
|
|
- All code projects must use the Apache License version 2.0.
|
|
- Documentation repositories must use Creative Commons License version 4.0.
|
|
- All OWNERS must be members of the Knative community.
|
|
- Repository creation must be approved by the Technical Oversight Committee.
|
|
|
|
### Requirements for Repository Donation
|
|
|
|
The Technical Oversight Committee may allow repositories to be donated to the
|
|
Knative project. In _addition_ to meeting the core repository requirements,
|
|
donated repositories must:
|
|
|
|
- Adopt the Google CLA bot.
|
|
- All contributors to the donated repository must have signed the Google CLA.
|
|
- All code must adopt the standard Knative header, attributing copyright as
|
|
follows: `"Copyright <year> The Knative Authors"`.
|
|
- Additions of the standard Knative header to code created by the contributors
|
|
can occur post-transfer, but should ideally occur shortly thereafter.
|
|
- An `AUTHORS` file should be created in the repo root, if one does not already
|
|
exist, that includes the original authors of the code. See
|
|
[knative/serving AUTHORS](https://github.com/knative/serving/blob/main/AUTHORS)
|
|
for reference.
|
|
- Note that copyright notices should only be modified or removed by the people
|
|
or organizations named in the notice.
|
|
|
|
## Removing Repositories
|
|
|
|
As important as it is to add new repositories, it is equally important to prune
|
|
repositories when necessary. See [Grounds for removal](#grounds-for-removal).
|
|
|
|
It is important to the success of Knative that all Knative repositories stay
|
|
active, healthy, and aligned with the scope and mission of project.
|
|
|
|
### Grounds for removal
|
|
|
|
Core repositories may be removed from the project if they are deemed _inactive_.
|
|
Inactive repositories are those that meet any of the following criteria:
|
|
|
|
- There are no longer any active maintainers for the project, and no
|
|
replacements can be found.
|
|
- All PRs and issues have gone un-addressed for longer than six months.
|
|
- There have been no new commits or other changes in more than a year.
|
|
- The contents have been folded into another actively maintained project.
|
|
|
|
### Procedure for removal
|
|
|
|
When a repository has been deemed eligible for removal, we take the following
|
|
steps:
|
|
|
|
- A proposal to remove the repository is brought to the attention of the
|
|
Technical Oversight Committee through a GitHub issue posted in the
|
|
[community](https://github.com/knative/community) repo.
|
|
- Feedback is encouraged during a Steering Committee meeting before
|
|
any action is taken.
|
|
- Once the Steering Committee has approved of the removal, if the repo is not moving to another
|
|
actively maintained project:
|
|
- The repo description is edited to start with the phrase "[EOL]"
|
|
- All open issues and PRs are closed
|
|
- All external collaborates are removed
|
|
- All webhooks, apps, integrations, or services are removed
|
|
- GitHub pages are disabled
|
|
- The repo is marked as archived using GitHub's archive feature
|
|
- The removal is announced on the knative-dev mailing list
|
|
- Documentation is removed / updated as appropriate from the knative/docs website
|
|
|
|
This procedure maintains the complete record of issues, PRs, and other
|
|
contributions. It leaves the repository read-only and makes it clear that the
|
|
repository is retired and no longer maintained.
|
|
|
|
## Additional / Experimental Repositories
|
|
|
|
It is beneficial for Knative working groups to be able to own code outside the
|
|
core `knative` organization, which is kept intentionally small and has a high
|
|
bar for entry. The `knative-extensions` GitHub organization was created for this
|
|
purpose. Repositories in `knative-extensions` are intended to give working groups
|
|
more latitude to experiment with new ideas and to self-organize and manage
|
|
contributions which may be important to the project but which do not need the
|
|
level of governance of the core project.
|
|
|
|
Note that `knative-extensions` is **not** an incubation area for projects entering
|
|
the `knative` github org; in most cases, projects in the extensions will remain
|
|
there for the entire duration. `knative-extensions` also provides a location for
|
|
implementations of core interfaces which do not themselves need to be part of
|
|
every knative installation, such as networking or eventing integrations. In the
|
|
event that a working group wants a project in extensions to be considered for
|
|
transfer to the `knative` org, the request will be considered on a case-by-case
|
|
basis by joint decision of the Steering Committee and the Technical Oversight
|
|
Committee.
|
|
|
|
### Mechanics of working-group owned repositories in `knative-extensions`
|
|
|
|
#### Creation
|
|
|
|
Note: prior art here from the
|
|
[Kubernetes community](https://github.com/kubernetes/community/blob/master/github-management/kubernetes-repositories.md).
|
|
|
|
Working groups are allowed to request repositories that meet the following
|
|
requirements. The Steering Committee will maintain the process and
|
|
perform the repository creation steps to ensure that the following requirements
|
|
have been met:
|
|
|
|
- Vendor dependencies must be clearly called out, and participation must be open
|
|
to the community.
|
|
|
|
- If the repository is for integration with a specific technology vendor,
|
|
affiliation with that vendor must not be required for participation.
|
|
|
|
- Non-integration repositories should aim to avoid dependencies on
|
|
vendor-specific technology by publishing abstract interfaces which can be
|
|
implemented by multiple vendors. Those implementations are not required to
|
|
live in separate repositories.
|
|
|
|
- Must adopt the Knative CLA.
|
|
|
|
- Must adopt the Knative
|
|
[code of conduct](https://github.com/knative/community/blob/main/CODE-OF-CONDUCT.md).
|
|
|
|
- Must adopt the Apache 2.0 license.
|
|
|
|
- Must be sponsored by a specific working group, which should be designated in
|
|
the `README.md` for the repo. In addition, at least one WG lead must be in the
|
|
root-level OWNERS file.
|
|
|
|
- Copyright assigned to The Knative Authors.
|
|
|
|
- Document clear release and install processes.
|
|
|
|
- Clearly document the stability and API guarantees (both in the top-level
|
|
`README.md` and by using appropriate API versioning for Kubernetes apigroups).
|
|
|
|
- The Steering Committee will maintain a template which will be used during the creation of
|
|
new repositories. Existing repositiories are encouraged to update their
|
|
`README`s from time to time as the format changes.
|
|
|
|
- Kubernetes APIs must be homed in a valid group with a DNS prefix approved by
|
|
the Steering Committee.
|
|
|
|
- APIs under `knative.dev` should:
|
|
|
|
1. Be under a subdomain managed by the owning Working Group (e.g.
|
|
`sources.knative.dev`, not `knative.dev`). The Steering Committee is considered the
|
|
authority for assigning subdomains to working groups.
|
|
|
|
1. Coordinate with the Working Group in API naming to avoid collisions or
|
|
confusing naming. This also includes API review by the responsible
|
|
Working Group to ensure consistency and alignment with duck-type field
|
|
naming.
|
|
|
|
Working groups must designate the repositories they own (by prefix or in the README.md of the repo, at a minimum).
|
|
|
|
Repositories owned by working groups are encouraged to embrace the project value
|
|
of pluggability.
|
|
|
|
### Non-requirements
|
|
|
|
The following are not required to create a working-group-owned repository:
|
|
|
|
- Steering approval (see ["the fine print"](#the-fine-print))
|
|
- Steering Committee approval
|
|
- Steering Committee may request certain naming patterns (e.g. `kn-plugin` for client WG)
|
|
- Solving an unique problem (exploring different approaches to problems outside
|
|
the core is actively encouraged!)
|
|
|
|
### The fine print
|
|
|
|
Steering reserve the right to require that repos be removed or
|
|
transferred out of the `knative-extensions` organization and API groups to be
|
|
renamed. This is intended to simplify the process in the common case, while
|
|
giving Steering the ability to step in and rectify problems that
|
|
may arise.
|
|
|
|
### Deletion
|
|
|
|
Working groups are responsible for the upkeep of their repositories and are
|
|
expected to keep a high quality bar. Inactive or non-conforming repositories
|
|
should be archived, deleted, or moved out of the `knative-extensions` organization,
|
|
following the general [Procedure for Removal](#procedure-for-removal) for
|
|
repositories.
|
|
|
|
## CLOMonitor and CLOTributor
|
|
|
|
[CLOMonitor](https://clomonitor.io/) is a CNCF tool that periodically checks open source projects repositories to verify they meet certain project health best practices.
|
|
|
|
[CLOTributor](https://clotributor.dev/) is a CNCF tool that makes it easier to discover great opportunities to become a Cloud Native contributor.
|
|
|
|
When a new repository is created, consider adding it to CLOMonitor [data file](https://github.com/cncf/clomonitor/blob/main/data/cncf.yaml), similar to:
|
|
|
|
```yaml
|
|
- name: eventing
|
|
url: https://github.com/knative/eventing
|
|
check_sets:
|
|
- code-lite
|
|
```
|
|
|
|
This will make the repository will be listed in CLOMonitor's Knative project [health report](https://clomonitor.io/projects/cncf/knative). It will also make CLOTributor to list `good-first-issue`s of the new repository.
|
|
|
|
If you would like to exclude the repository from the health report but have the `good-first-issues` in CLOTributor, add following the field:
|
|
|
|
```yaml
|
|
exclude:
|
|
- clomonitor
|
|
```
|
|
|
|
Based on the maturity of the repository, it is possible to use different `check_sets`. See CLOMonitor's [checks documentation](https://github.com/cncf/clomonitor/blob/main/docs/checks.md) for more information.
|
|
|
|
---
|
|
|
|
Contents of this page are adopted from the
|
|
[Kubernetes repository guidelines](https://github.com/kubernetes/community/blob/master/github-management/kubernetes-repositories.md),
|
|
which is licensed under Apache License 2.0.
|
|
|
|
Except as otherwise noted, the content of this page is licensed under the
|
|
[Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/),
|
|
and code samples are licensed under the
|
|
[Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0).
|