Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add new repository structure doc. #1752

Merged
merged 2 commits into from Feb 15, 2018

Conversation

@brendandburns
Copy link
Contributor

brendandburns commented Feb 7, 2018

This is a general proposal from the Kubernetes steering committee. I authored the pull, but the document is jointly authored.

@bgrant0607 @thockin @timothysc @michelleN @smarterclayton @derekwaynecarr @quinton-hoole @sarahnovotny @jbeda @spiffxp @pwittrock @philips

We plan on discussing this at Kubernetes community meeting on 2/8/2018

@thockin

This comment has been minimized.

Copy link
Member

thockin commented Feb 7, 2018

LGTM

@fejta

fejta approved these changes Feb 7, 2018

Copy link
Contributor

fejta left a comment

Looks like a real good state of affairs! Excited to help write any necessary automation to make this a positive change for everyone.


#### Rules

* For now all repos will live in github.com/kubernetes-sigs/<sig-name>-<project-name>, this may change in the future as we see how things work.

This comment has been minimized.

@fejta

fejta Feb 7, 2018

Contributor

I think you want \<sig-name>-\<project-name> as right now this renders as github.com/kubernetes-sigs/- over at https://github.com/brendandburns/community/blob/e14f28997ef64429a83eefc02568e130f81db8cb/kubernetes-repositories.md

This comment has been minimized.

@mattfarina

mattfarina Feb 7, 2018

Member

So, if konflate was moved there it would be a repo called cli-konflate (sponsored by sig cli).

This comment has been minimized.

@brendandburns

brendandburns Feb 14, 2018

Author Contributor

yes, that's correct.

This comment has been minimized.

@brendandburns

brendandburns Feb 14, 2018

Author Contributor

although I switched to underscore (_) instead of dash (-) since dash is blocked from package names.


### Core Repositories

Core repositories are considered core components of Kubernetes. They are utilities, tools, applications, or libraries that are expected to be present in every or nearly every Kubernetes cluster, such as components and tools included in official Kubernetes releases. Additionally, the kubernetes.io website, k8s.io machinery, and other project-wide infrastructure will remain in the kubernetes github organization.

This comment has been minimized.

@idvoretskyi

idvoretskyi Feb 7, 2018

Member

Additionally, the kubernetes.io website, k8s.io machinery, and other project-wide infrastructure will remain in the kubernetes github organization.

IMO, it makes sense to define the list of those more precisely. Most of them are de-facto owned by the single SIG (eg. features -> SIG-PM; sig-release -> SIG-Release; website -> SIG-Docs, etc.), but have an impact on the whole Kubernetes project.

This comment has been minimized.

@brendandburns

brendandburns Feb 14, 2018

Author Contributor

not sure I want to spell them all out in this doc... I think the intent is clear, but the specific list is likely to change over time.

@spiffxp

This comment has been minimized.

Copy link
Member

spiffxp commented Feb 7, 2018

/committee steering
/hold
for comment

#### Rules

* Must adopt the Kubernetes Code of Conduct statement in their repo.
* All code projects use the Apache License version 2.0. Documentation repositories should use the Creative Commons License version 4.0.

This comment has been minimized.

@ncdc

ncdc Feb 7, 2018

Member

"should" or "must" for doc repos? What if it's "should" and a doc repo isn't using CCv4?

This comment has been minimized.

@bgrant0607

bgrant0607 Feb 7, 2018

Member

Yes, must.

This comment has been minimized.

@brendandburns

brendandburns Feb 14, 2018

Author Contributor

fixed.


* For now all repos will live in github.com/kubernetes-sigs/<sig-name>-<project-name>, this may change in the future as we see how things work.
* Must adopt the Kubernetes Code of Conduct
* All code projects use the Apache License version 2.0. Documentation repositories should use the Creative Commons License version 4.0.

This comment has been minimized.

@ncdc

ncdc Feb 7, 2018

Member

Same q as above re should vs must

This comment has been minimized.

@brendandburns

brendandburns Feb 14, 2018

Author Contributor

fixed.


* Must live under github.com/kubernetes/<project-name>
* Must adopt the Kubernetes Code of Conduct
* All code projects use the Apache Licence version 2.0. Documentation repositories should use the Creative Commons License version 4.0.

This comment has been minimized.

@ncdc

ncdc Feb 7, 2018

Member

And again here

This comment has been minimized.

@brendandburns

brendandburns Feb 14, 2018

Author Contributor

fixed.

@timothysc

This comment has been minimized.

Copy link
Member

timothysc commented Feb 7, 2018

I had a general question come up the other day which was: "Given this new structure, what should be in vs. out for docs, b/c it crosses a lot of lines today". @kris-nova @Bradamant3


*Much of the things needed (e.g. CLA Bot integration) is missing to support associated projects. Many things seem vague. Halp!*

True, we need to improve these things. For now, do the best you can to conform to the spirit of the proposal (e.g. post the code of conduct, etc)

This comment has been minimized.

@MHBauer

MHBauer Feb 7, 2018

Member

Writing these requirements down is a good first step. Someone can take this as evidence or belief to drive actions towards doing the next steps of making the tooling adaptable for this purpose..

* For now all repos will live in github.com/kubernetes-sigs/<sig-name>-<project-name>, this may change in the future as we see how things work.
* Must adopt the Kubernetes Code of Conduct
* All code projects use the Apache License version 2.0. Documentation repositories should use the Creative Commons License version 4.0.
* Must adopt the CNCF CLA bot, merge bot and Kubernetes PR commands/bots.

This comment has been minimized.

@mattfarina

mattfarina Feb 7, 2018

Member

Why must all repos adopt the merge automation and PR commands/bots (I assume associated with merge automation)?

I ask due to contributor experience. k8s merge automation is not common. It solves a real problem for the monorepo but it's not common among k8s repos or repos outside of k8s and many folks who are involved in existing k8s repos, many of whom don't use the merge automation, don't understand how it works. If you use it regularly it makes sense but that's a subset of people.

From my perspective, I keep getting asked how it works. Sometimes folks I have explained it to come back and ask a couple months later because it's been that long since they dealt with it.

If everyone is going to have to use it the UX of the solution needs to be improved so the long tail of folks can navigate it.

This comment has been minimized.

@brendandburns

brendandburns Feb 14, 2018

Author Contributor

We want consistent experience for all projects that are associated with Kubernetes, for example two-factor auth, merge via bot/test rather than human, etc.

Given that you can always build an associated repository which has lighter responsibility.

@perotinus

This comment has been minimized.

Copy link
Member

perotinus commented Feb 7, 2018

What does this proposal imply for projects like Helm? I don't think Helm is "expected to be present in every or nearly every Kubernetes cluster". In fact, there are several projects in the k/ org that do not need to be present in every cluster, e.g., ingress-gce, ingress-nginx.


### Associated Repositories

Associated repositories conform to the Kubernetes community standards for a repository, but otherwise have no restrictions. Associated repositories exist solely for the purpose of making it easier for the Kubernetes community to work together. There is no implication of support or endorsement of any kind by the Kubernetes project, the goals are purely logistical.

This comment has been minimized.

@sebgoa

sebgoa Feb 8, 2018

Member

it should specify somewhere if those repos are brand new or can be existing repos that are migrated to the "kubernetes" org at large.

This comment has been minimized.

@brendandburns

brendandburns Feb 14, 2018

Author Contributor

I think that this applies to both types of repositories, both new ones and ones that might be migrated out of incubator.

But we're not going to try to modify the status quo, we won't force repositories to move...

@michelleN

This comment has been minimized.

Copy link
Member

michelleN commented Feb 8, 2018

@perotinus For now, things will still as they are. See this FAQ answer for more info

* All code projects use the Apache License version 2.0. Documentation repositories should use the Creative Commons License version 4.0.
* Must adopt the CNCF CLA bot, merge bot and Kubernetes PR commands/bots.
* All OWNERS of the project must also be active SIG members.
* SIG membership must vote using lazy consensus to create a new repository

This comment has been minimized.

@bgrant0607

bgrant0607 Feb 8, 2018

Member

Discussed in SIG Arch today:

SIG must already have identified all of their existing subprojects and code, with valid OWNERS files, in sigs.yaml:
https://github.com/kubernetes/community/blob/master/sigs.yaml

This comment has been minimized.

@brendandburns

brendandburns Feb 14, 2018

Author Contributor

added.


#### Rules

* For now all repos will live in github.com/kubernetes-sigs/<sig-name>-<project-name>, this may change in the future as we see how things work.

This comment has been minimized.

@hoegaarden

hoegaarden Feb 9, 2018

Member

That means, that each repo has a - in its name. Package names with dashes are not allowed in go. This forces people to have different names for the package then for the repo.

This comment has been minimized.

@brendandburns

brendandburns Feb 14, 2018

Author Contributor

Fixed to underscore.


To provide a place for SIGs to collaborate on projects endorsed by and actively worked on by members of the SIG. SIGs should be able to approve and create new repositories for SIG-sponsored projects without requiring higher level approval from a central body (e.g. steering committee or sig-architecture)

#### Rules

This comment has been minimized.

@hoegaarden

hoegaarden Feb 9, 2018

Member

Do we want to have guidelines to setup some common teams for those repos? E.g.:

  • <signame>-<project>-reviewers
  • <signame>-<project>-admins
  • <signame>-<project>-bots

I think the bots may be useful, I like the reviewers team for tagging them on PRs to ask for, well, reviews, ... I am not sure if there should be more teams.

This comment has been minimized.

@brendandburns

brendandburns Feb 14, 2018

Author Contributor

I will do a separate doc with concrete process.

This comment has been minimized.

## Kubernetes Repositories


This document attempts to describe a process for creating and associating github repositories with the Kubernetes project.

This comment has been minimized.

@spiffxp

spiffxp Feb 13, 2018

Member

I don't see a process described here

This comment has been minimized.

@timothysc

timothysc Feb 14, 2018

Member

s/describe a process/outline a structure

This comment has been minimized.

@brendandburns

brendandburns Feb 14, 2018

Author Contributor

fixed.

@k8s-ci-robot

This comment has been minimized.

Copy link
Contributor

k8s-ci-robot commented Feb 14, 2018

Thanks for your pull request. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please follow instructions at https://git.k8s.io/community/CLA.md#the-contributor-license-agreement to sign the CLA.

It may take a couple minutes for the CLA signature to be fully registered; after that, please reply here with a new comment and we'll verify. Thanks.


Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. I understand the commands that are listed here.

@brendandburns

This comment has been minimized.

Copy link
Contributor Author

brendandburns commented Feb 14, 2018

@timothysc regarding docs, I think that kubernetes.io are core repositories, some more specialized docs (e.g. "how to run a scale test") might be a SIG level repository.

Third party docs ("tutorial on using Foo with Kubernetes") could be associated repositories.

@brendandburns

This comment has been minimized.

Copy link
Contributor Author

brendandburns commented Feb 14, 2018

Comments addressed, I think that this is ready to merge unless there are other questions or concerns.

#### Rules
* Must live under github.com/kubernetes/<project-name>

This comment has been minimized.

@bgrant0607

bgrant0607 Feb 15, 2018

Member

Backslashes or backticks are needed here

This comment has been minimized.

@brendandburns

brendandburns Feb 15, 2018

Author Contributor

done.

@bgrant0607

This comment has been minimized.

Copy link
Member

bgrant0607 commented Feb 15, 2018

@brendandburns Your 2nd commit isn't signed properly, so it's not passing the CLA bot. Please fix that, address the one formatting issue, and squash.

Otherwise, lgtm

@brendandburns brendandburns force-pushed the brendandburns:repos branch from 456a6cd to 8445469 Feb 15, 2018

@brendandburns

This comment has been minimized.

Copy link
Contributor Author

brendandburns commented Feb 15, 2018

Comment addressed, commit fixed.

Please re-check.

Thanks!

@bgrant0607

This comment has been minimized.

Copy link
Member

bgrant0607 commented Feb 15, 2018

/lgtm

@k8s-ci-robot

This comment has been minimized.

Copy link
Contributor

k8s-ci-robot commented Feb 15, 2018

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: bgrant0607, brendandburns

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:
  • OWNERS [bgrant0607,brendandburns]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-ci-robot k8s-ci-robot merged commit 21772bf into kubernetes:master Feb 15, 2018

3 checks passed

cla/linuxfoundation brendanburns authorized
Details
pull-community-verify Job succeeded.
Details
tide In tide pool.
Details

#### Rules

* For now all repos will live in github.com/kubernetes-sigs/\<sig-name\>_\<project-name\>, this may change in the future as we see how things work.

This comment has been minimized.

@lavalamp

lavalamp Mar 6, 2018

Member

I agree with the email comment that this naming convention is a ux disaster. I can think of two improvements:

  1. At least drop the "sig" from the sig name, e.g. kubernetes-sigs/api-machinery_foobar rather than kubernetes-sigs/sig-api-machinery_foobar
  2. Give each sig a 2, 3, or 4 letter code. Then we can also switch to a dash rather than mix dashes and underscores. E.g., kubernetes-sigs/apim-foobar. Tracking short names for all sigs would be useful in other contexts, too, I think.

This comment has been minimized.

@erictune

erictune Mar 6, 2018

Member

Agree on UX disaster.

Two other alternatives:

  • remove sig name entirely from the repo name and move it to the repo title (which can be known from GH API). E.g. kubernetes-sigs/foobar with title foobar: Foos your bars, maintained by #sig-api-machinery
  • put entire sig name in a well known file such as .prow/signame. e.g. repo is called kubernetes-sigs/foobar and contains .prow/signame with contents sig-api-machinery.

This comment has been minimized.

@ddysher

ddysher Mar 12, 2018

Contributor

Another alternative is to use GitHub topics; github allows searching topics within an org, which is better than just use prefixes.

### Core Repositories
Core repositories are considered core components of Kubernetes. They are utilities, tools, applications, or libraries that are expected to be present in every or nearly every Kubernetes cluster, such as components and tools included in official Kubernetes releases. Additionally, the kubernetes.io website, k8s.io machinery, and other project-wide infrastructure will remain in the kubernetes github organization.

This comment has been minimized.

@lavalamp

lavalamp Mar 6, 2018

Member

What about client libraries?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.