Merge branch 'master' of github.com:kubernetes/community

4 files changed, 292 insertions, 0 deletions

diff --git a/github-management/kubernetes-repositories.md b/github-management/kubernetes-repositories.md
index 22133bc9..803d9b1c 100644
--- a/github-management/kubernetes-repositories.md
+++ b/github-management/kubernetes-repositories.md
@@ -22,6 +22,9 @@ against the kubernetes/org repo.
 - [Core Repositories](#core-repositories)
   * [Goals](#goals-2)
   * [Rules](#rules-1)
+- [Creating Repositories](#creating-repositories)
+  * [Non-staging repositories](#non-staging-repositories)
+  * [Staging repositories](#staging-repositories)
 - [Removing Repositories](#removing-repositories)
   * [Grounds for removal](#grounds-for-removal)
   * [Procedure for removal](#procedure-for-removal)
@@ -98,6 +101,13 @@ the developers who could not be reached
      [@caniszczyk](https://github.com/caniszczyk) for review of third party deps
    * Boilerplate text across all files should attribute copyright as follows:
      `"Copyright <Project Authors>"` if no CLA was in place prior to donation
+   * Additions of [the standard Kubernetes header](https://git.k8s.io/kubernetes/hack/boilerplate/boilerplate.go.txt)
+     to code created by the contributors can occur post-transfer, but should
+     ideally occur shortly thereafter.
+
+Note that copyright notices should only be modified or removed by the people or
+organizations named in the notice. See [the FAQ below](#faq) for more information
+regarding copyrights and copyright notices.
 
 ## Core Repositories
 
@@ -127,6 +137,64 @@ ecosystem. Carries the endorsement of the Kubernetes community.
      Kubernetes steering committee elections. in the Kubernetes community
    * Repository must be approved by SIG-Architecture
 
+## Creating Repositories
+
+### Non-staging repositories
+
+For non-staging repositories, suggestions on how to create
+a new repository are described below.
+
+  * Ensure that the repo creation request has appropriate approvals
+  as per the rules mentioned above.
+  * Using the organization and repository name mentioned in the repo creation
+  request, create a new repo with default GitHub settings.
+  * Set the description as per the repo creation request.
+  * Clone the newly created repo locally.
+  * Copy the latest contents of [kubernetes-template-project] and create an
+  initial commit with the message *Initial commit from the
+  kubernetes-template-project*.
+  * Make the following changes in the next commit:
+    * If the request references a GitHub team to be listed in the `OWNERS`
+    file, update the `OWNERS_ALIASES` file to remove the steering-committee
+    alias and add a new alias for the team with members populated as per the
+    GitHub team. If the request does not reference a GitHub team, remove the
+    `OWNERS_ALIASES` file.
+    * Update the OWNERS file as per the request. If the repo is a
+    [SIG Repository], add a labels entry for the SIG that the repo belongs to.
+    * Update the `SECURITY_CONTACTS` file as per the request. Note that aliases
+    cannot be used in this case so expand the GitHub team, if specified.
+    * Create a new commit with the message *Update OWNERS, OWNERS_ALIASES and
+    SECURITY_CONTACTS*.
+  * Push the new commits directly to the master branch.
+  * If the repo is a [SIG Repository], add a new topic of the form
+  `k8s-sig-<sig-name-repo-belongs-to>` using the *Manage Topics* option.
+  * Create a PR against [kubernetes/org] to add teams as per the [team guidance]
+  for alloting repo admin and write access.
+  * Once the above PR is merged and the postsubmit has run, the new GitHub teams
+  will be created. In the *Collaborators and Teams* section in Settings,
+  assign the new teams appropriate access to the repo.
+  * Ask the author of the repo creation request to add the repo
+  as a part of a subproject in [`sigs.yaml`](/sigs.yaml).
+
+### Staging Repositories
+
+If the repository is a staging repository, there are some deviations
+from the above procedure:
+
+  * The repository **must** have an initial empty commit. The contents of the
+  repo will be populated from staging by the [publishing-bot].
+  * Grant the [@kubernetes/stage-bots] team admin access to the repo.
+  * Setup branch protection and enable access to the
+  `stage-bots` team by adding the repo in
+  [`prow/config.yaml`](https://git.k8s.io/test-infra/prow/config.yaml). See
+  [kubernetes/test-infra#9292](https://github.com/kubernetes/test-infra/pull/9292)
+  for an example.
+  * Once the repo has been created, add the repo to
+  [`hack/fetch-all-latest-and-push.sh`](https://git.k8s.io/publishing-bot/hack/fetch-all-latest-and-push.sh)
+  in the [publishing-bot] repo.
+
+<!-- TODO: Add suggestions for how to migrate existing repos -->
+
 ## Removing Repositories
 
 As important as it is to add new repositories, it is equally important to prune
@@ -168,6 +236,8 @@ steps:
   * All webhooks, apps, integrations or services are removed
   * GitHub Pages are disabled
   * The repo is marked as archived using [GitHub's archive feature]
+  * Remove all teams associated with the repo
+  * Remove the repo from [sigs.yaml]
   * The removal is announced on the kubernetes-dev mailing list and community
     meeting
 
@@ -175,6 +245,9 @@ This maintains the complete record of issues, PRs and other contributions,
 leaves the repository read-only, and makes it clear that the repository should
 be considered retired and unmaintained.
 
+In case a repository has only the initial commits adding template files
+and no additional activity, it can be completely deleted.
+
 ## FAQ
 
 **My project is currently in kubernetes-incubator, what is going to happen to
@@ -220,6 +293,27 @@ associated projects. Many things seem vague. Help!**
 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)
 
+**When I donate my project, am I transferring my copyrights?**
+
+No. All contributors retain ownership of their copyrights in the code they donate.
+Instead, they are granting a license to the project (that's the 'L' in 'CLA').
+
+For consistency and efficiency in complying with notice requirements, code that is
+donated to a Kubernetes repo should use [the standard header](https://git.k8s.io/kubernetes/hack/boilerplate/boilerplate.go.txt)
+referencing "The Kubernetes Authors". That doesn't mean you are transferring your
+copyright. Instead, it's a general reference to the fact that the copyrights remain
+owned by the authors of Kubernetes.
+
+Note that you should _never_ modify or remove a third party's copyright notice if
+you are not authorized by them to do so.
+
 [GitHub's archive feature]:
 https://help.github.com/articles/archiving-a-github-repository/
 [kubernetes-retired]: https://github.com/kubernetes-retired
+[kubernetes-template-project]: https://github.com/kubernetes/kubernetes-template-project
+[kubernetes/org]: https://github.com/kubernetes/org
+[team guidance]: /github-management/org-owners-guide.md#team-guidance
+[SIG Repository]: #sig-repositories
+[publishing-bot]: https://github.com/kubernetes/publishing-bot
+[@kubernetes/stage-bots]: https://github.com/orgs/kubernetes/teams/stage-bots
+[sigs.yaml]: /sigs.yaml
diff --git a/github-management/opening-a-request.md b/github-management/opening-a-request.md
index dd7724cb..90c136a9 100644
--- a/github-management/opening-a-request.md
+++ b/github-management/opening-a-request.md
@@ -15,6 +15,10 @@ If you need help with the following:
 Please open an issue against the [kubernetes/org] repository describing your
 issue. If your request is urgent, please escalate to **[@kubernetes/owners]**.
 
+To create a new team, add a member to a team or rename a team, please
+create a PR against the [kubernetes/org] repository according to
+the [team guidance].
+
 ## Bot/Automation issues
 
 If you need help with the following:
@@ -32,3 +36,4 @@ your issue. If your request is urgent, please escalate to the
 [@kubernetes/owners]: https://github.com/orgs/kubernetes/teams/owners
 [kubernetes/test-infra]: https://github.com/kubernetes/test-infra/issues
 [test-infra on-call]: https://go.k8s.io/oncall
+[team guidance]: /github-management/org-owners-guide.md#team-guidance
diff --git a/github-management/org-owners-guide.md b/github-management/org-owners-guide.md
index 09df20ad..476c71f5 100644
--- a/github-management/org-owners-guide.md
+++ b/github-management/org-owners-guide.md
@@ -48,6 +48,8 @@ transfer in existing code.
 
 ## Team Guidance
 
+### Nomenclature
+
 Each organization should have the following teams:
 
 - teams for each repo `foo`
@@ -76,6 +78,35 @@ for all orgs going forward.  Notable discrepancies at the moment:
   org. This was a mistake that swapped the usual convention, and we would like
   to rename the team
 
+### Structure and Process
+
+Guidelines on how to create and structure teams are described below:
+
+#### Structure
+
+**Renaming a team**:
+
+To rename a team, add the `previously: <old-team-name>` field to the team
+and rename the `name` of the team to the new name.
+
+**Creating a team**:
+
+- Unless a member is part of the [@kubernetes/owners] team, they needed to be
+  added to the `members` list in the team. Members of the
+  [@kubernetes/owners] team *must* be added to the `maintainers` list because
+  of how the GitHub API works.
+- The `privacy` of a team *must* be `closed`.
+
+#### Process
+
+A new team can be created or a member can be added to a team by
+creating a PR against the [kubernetes/org] repo. The PR must be
+approved by the relevant `OWNERS` or the SIG leads.
+
+For example, addition of a member to `foo-maintainers` must be approved
+by the `OWNERS` of the repo `foo` or the leads of the SIG associated
+with the repo.
+
 ## Project Board Guidance
 
 Guidelines for project boards in the Kubernetes GitHub orgs are described below:
@@ -109,3 +140,4 @@ Project](https://github.com/kubernetes/kubernetes-template-project), and the
 [GitHub Administration Team]:
 /github-management/README.md#github-administration-team
 [@kubernetes/owners]: https://github.com/orgs/kubernetes/teams/owners
+[kubernetes/org]: https://github.com/kubernetes/org
diff --git a/github-management/subproject-site-requests.md b/github-management/subproject-site-requests.md
new file mode 100644
index 00000000..c5d7a661
--- /dev/null
+++ b/github-management/subproject-site-requests.md
@@ -0,0 +1,161 @@
+# Subproject Site Requests
+
+Official Kubernetes subprojects can request a domain and site hosting for
+their project specific documentation. The Kubernetes community has standardized
+on [Netlify] for this purpose. Netlify was chosen for its ease of use,
+integrations such as offering automatic site previews per PR, and its support
+for multiple site generation frameworks.
+
+**NOTE:** This process is only for requesting a domain and hosting, not the
+building and design of the site itself. The responsibility for maintaining the
+subproject site belongs to the subproject itself.
+
+If you are unsure of what site framework to use, [Hugo] is a lightweight Go
+based framework. It's used for the Kubernetes website and several subprojects.
+
+
+- [Requesting a Netlify Site](#requesting-a-netlify-site)
+  - [Example Netlify Configuration](#example-netlify-configuration)
+- [Requesting a Subproject Domain](#requesting-a-subproject-domain)
+  - [Example Subproject Domain Request](#example-subproject-domain-request)
+- [Processing a Netlify Site Request](#processing-a-netlify-site-request)
+
+
+## Requesting a Netlify Site
+
+- Update the project to include a [site specific][site-config] configuration
+  file at the root of the repository ([`netlify.toml`][site-config]).
+  [Below](#example-netlify-configuration) is a [Hugo] based example that you
+  may use as a reference.
+
+- Create an issue in the [kubernetes/org] repository using the
+  [Netlify Site Request Template]. It will ask for:
+  - Requesting sub-project and associated information. Linking to an issue or
+    other supporting material for the Netlify request associated with the
+    subproject is encouraged and will speed processing of the request.
+  - Desired domain name. It should follow the pattern of
+    `<sub-project>.sigs.k8s.io` and match the
+    [request](#requesting-a-subproject-domain) for a subproject domain.
+
+- A member of the GitHub Admin team handling Netlify requests will respond and
+  follow up with any questions in the issue.
+
+- Once Netlify has been configured, you can preview the site using the Netlify
+  URL (example: `kubernetes-sigs-foo.netlify.com`). After this looks good to you,
+  [request a subproject domain](#subproject-domain-request) and reference the
+  issue you created.
+
+Once complete, the site should be accessible.
+
+### Example Netlify Configuration
+
+```toml
+[build]
+base = "site/"
+publish = "site/public/"
+command = "hugo"
+
+[build.environment]
+HUGO_VERSION = "0.53"
+
+[context.production.environment]
+HUGO_ENV = "production"
+HUGO_BASEURL = "https://foo.sigs.k8s.io/"
+
+[context.deploy-preview]
+command = "hugo --enableGitInfo --buildFuture -b $DEPLOY_PRIME_URL"
+
+[context.branch-deploy]
+command = "hugo --enableGitInfo --buildFuture -b $DEPLOY_PRIME_URL"
+  ```
+
+## Requesting a Subproject Domain
+
+Subproject domains may be requested for a Kubernetes Org managed Netlify site in
+the form of: `<project>.sigs.k8s.io`.
+
+To do so, create an issue using the [DNS Update Request] issue template in the
+[kubernetes/k8s.io] repository. Use the below guidelines for your
+[DNS Update Request].
+
+- **Type of DNS update:** Create
+- **Domain being modified:** `k8s.io`
+- **New DNS Record:**
+  ```yaml
+  # https://github.com/kubernetes-sigs/<project> (<contact or owners>)
+  <project>.sigs:
+    type: CNAME
+    value: <netlify url>
+  ```
+- **Reason for update:** Provide a description and link to the Netlify request
+  issue made in [kubernetes/org].
+
+
+### Example Subproject Domain Request
+
+````
+### Type of DNS update:
+Create
+
+### Domain being modified:
+k8s.io
+
+### New DNS Record:
+```yaml
+# https://github.com/kubernetes-sigs/foo (@bar)
+foo.sigs:
+  type: CNAME
+  value: kubernetes-sigs-foo.netlify.com
+  ```
+### Reason for update:
+The sig-foo subproject has requested a netlify site to host its documentation. ref #0000, #0000.
+````
+
+
+## Processing a Netlify Site Request
+
+**NOTE:** For use by the GitHub Admin team. You must be both an Org owner and
+Netlify admin to follow the procedure.
+
+- Login to [Netlify] and from the home dashboard select **New Site from Git**.
+
+- On the _"Create a new site"_ page, select GitHub. It will then prompt you to
+  authorize the application for the desired GitHub Organization. Select the
+  GitHub Organization and the desired repo.
+
+- In the _"Deploy Options"_ ensure the **Owner** is set to `Kubernetes Docs` and
+  **Branch to deploy** is set to `master`. The _"Basic build settings"_ will be
+  autopopulated with the values provided in `netlify.toml`. Deploy the site.
+  It will take you to the _"Site overview"_ page.
+
+- Navigate to the **Site Settings** and then change the Site name following the
+  convention `kubernetes-sigs-<repo/project name>` e.g. `kubernetes-sigs-foo`.
+  This will be used as both the Netlify site name and in the auto-generated PR
+  based previews.
+
+- From the left hand menu, select **Domain management**.
+
+- Select **[Add custom domain]**. Then enter the domain name requested in the
+  issue. It should follow the pattern of `<subproject-name>.sigs.k8s.io`.
+  Note that HTTPS will not be enabled right away. Once the DNS configuration is
+  updated, HTTPS will be enabled automatically.
+
+- Follow up with the requestor in the issue and let them know the site has been
+  deployed and give them the Netlify site url (site name + `netlify.com`).
+  Example `kubernetes-sigs-foo.netlify.com`. They may use this address for
+  testing and use before their DNS Request has been processed.
+
+Once complete, the rest of the Netlify site configuration can be handled by the
+project owner in their [netlify.toml][site-config] config.
+
+
+[netlify]: https://www.netlify.com/
+[kubernetes website]: https://git.k8s.io/website
+[hugo]: https://gohugo.io
+[dns update request]: https://github.com/kubernetes/k8s.io/issues/new/choose
+[kubernetes/org]: https://git.k8s.io/org
+[kubernetes/k8s.io]: https://git.k8s.io/k8s.io
+[netlify site request template]: https://github.com/kubernetes/org/issues/new/choose
+[dns zone config]: https://git.k8s.io/k8s.io/dns/zone-configs/k8s.io.yaml
+[site-config]: https://www.netlify.com/docs/netlify-toml-reference/
+[add custom domain]: https://www.netlify.com/docs/custom-domains/
\ No newline at end of file