Add contributing docs (koordinator-sh#29)

Signed-off-by: Siyu Wang <[email protected]>

.github/workflows/ci.yaml

@@ -3,6 +3,7 @@ name: CI
 on:
   push:
     branches:
+      - main
       - master
       - release-*
   pull_request: {}
@@ -62,11 +63,12 @@ jobs:
       - name: Run Unit Tests
         run: |
           make test
-          git status
       - name: Publish Unit Test Coverage
         uses: codecov/codecov-action@v1
         with:
           flags: unittests
           file: cover.out
       - name: Check diff
-        run: '[[ -z $(git status -s) ]] || (printf "Existing modified/untracked files.\nPlease run \"make generate manifests\" and push again.\n"; exit 1)'
+        run: |
+          git status
+          [[ -z $(git status -s) ]] || (printf "Existing modified/untracked files.\nPlease run \"make generate manifests\" and push again.\n"; exit 1)

.github/workflows/license.yml

@@ -2,6 +2,7 @@ name: License
 on:
   push:
     branches:
+      - main
       - master
       - release-*
   workflow_dispatch: {}

CONTRIBUTING.md

@@ -0,0 +1,132 @@
+# Contributing to Koordinator
+
+Welcome to Koordinator! Koordinator consists several repositories under the organization.
+We encourage you to help out by reporting issues, improving documentation, fixing bugs, or adding new features.
+
+Please also take a look at our code of conduct, which details how contributors are expected to conduct themselves as part of the Koordinator community.
+
+## Reporting issues
+
+To be honest, we regard every user of Koordinator as a very kind contributor.
+After experiencing Koordinator, you may have some feedback for the project.
+Then feel free to open an issue.
+
+There are lot of cases when you could open an issue:
+
+- bug report
+- feature request
+- performance issues
+- feature proposal
+- feature design
+- help wanted
+- doc incomplete
+- test improvement
+- any questions on project
+- and so on
+
+Also we must remind that when filing a new issue, please remember to remove the sensitive data from your post.
+Sensitive data could be password, secret key, network locations, private business data and so on.
+
+## Code and doc contribution
+
+Every action to make Koordinator better is encouraged.
+On GitHub, every improvement for Koordinator could be via a PR (short for pull request).
+
+- If you find a typo, try to fix it!
+- If you find a bug, try to fix it!
+- If you find some redundant codes, try to remove them!
+- If you find some test cases missing, try to add them!
+- If you could enhance a feature, please DO NOT hesitate!
+- If you find code implicit, try to add comments to make it clear!
+- If you find code ugly, try to refactor that!
+- If you can help to improve documents, it could not be better!
+- If you find document incorrect, just do it and fix that!
+- ...
+
+### Workspace Preparation
+
+To put forward a PR, we assume you have registered a GitHub ID.
+Then you could finish the preparation in the following steps:
+
+1. **Fork** Fork the repository you wish to work on. You just need to click the button Fork in right-left of project repository main page. Then you will end up with your repository in your GitHub username.
+2. **Clone** your own repository to develop locally. Use `git clone https://github.com/<your-username>/<project>.git` to clone repository to your local machine. Then you can create new branches to finish the change you wish to make.
+3. **Set remote** upstream to be `https://github.com/koordinator-sh/<project>.git` using the following two commands:
+
+```bash
+git remote add upstream https://github.com/koordinator-sh/<project>.git
+git remote set-url --push upstream no-pushing
+```
+
+Adding this, we can easily synchronize local branches with upstream branches.
+
+4. **Create a branch** to add a new feature or fix issues
+
+Update local working directory:
+
+```bash
+cd <project>
+git fetch upstream
+git checkout main
+git rebase upstream/main
+```
+
+Create a new branch:
+
+```bash
+git checkout -b <new-branch>
+```
+
+Make any change on the new-branch then build and test your codes.
+
+### PR Description
+
+PR is the only way to make change to Koordinator project files.
+To help reviewers better get your purpose, PR description could not be too detailed.
+We encourage contributors to follow the [PR template](./.github/PULL_REQUEST_TEMPLATE.md) to finish the pull request.
+
+### Developing Environment
+
+As a contributor, if you want to make any contribution to Koordinator project, we should reach an agreement on the version of tools used in the development environment.
+Here are some dependents with specific version:
+
+- Golang : v1.17+
+- Kubernetes: v1.20+
+
+### Developing guide
+
+There's a `Makefile` in the root folder which describes the options to build and install. Here are some common ones:
+
+```bash
+# Generate code (e.g., apis, clientset, informers) and manifests (e.g., CRD, RBAC YAML files)
+make generate manifests
+
+# Build the koord-manager and koordlet binary
+make build
+
+# Run the unit tests
+make test
+```
+
+### Proposals
+
+If you are going to contribute a feature with new API or needs significant effort, please submit a proposal in [./docs/proposals/](./docs/proposals) first.
+
+## Engage to help anything
+
+We choose GitHub as the primary place for Koordinator to collaborate.
+So the latest updates of Koordinator are always here.
+Although contributions via PR is an explicit way to help, we still call for any other ways.
+
+- reply to other's issues if you could;
+- help solve other user's problems;
+- help review other's PR design;
+- help review other's codes in PR;
+- discuss about Koordinator to make things clearer;
+- advocate Koordinator technology beyond GitHub;
+- write blogs on Koordinator and so on.
+
+In a word, **ANY HELP IS CONTRIBUTION**.
+
+## Join Koordinator as a member
+
+It is also welcomed to join Koordinator team if you are willing to participate in Koordinator community continuously and keep active.

README.md

@@ -25,7 +25,7 @@ You can view the full documentation from the [Koordinator website](https://koord
 
 ## Contributing
 
-...
+You are warmly welcome to hack on Koordinator. We have prepared a detailed guide [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

docs/proposals/YYYYMMDD-template.md

@@ -0,0 +1,191 @@
+---
+title: Proposal Template
+authors:
+  - "@XXX"
+reviewers:
+  - "@YYY"
+creation-date: yyyy-mm-dd
+last-updated: yyyy-mm-dd
+status: provisional|experimental|implementable|implemented|deferred|rejected|withdrawn|replaced
+see-also:
+  - "/docs/proposals/20190101-we-heard-you-like-proposals.md"
+  - "/docs/proposals/20190102-everyone-gets-a-proposal.md"
+replaces:
+  - "/docs/proposals/20181231-replaced-proposal.md"
+superseded-by:
+  - "/docs/proposals/20190104-superceding-proposal.md"
+---
+
+# Title
+
+- Keep it simple and descriptive.
+- A good title can help communicate what the proposal is and should be considered as part of any review.
+
+<!-- BEGIN Remove before PR -->
+To get started with this template:
+1. **Make a copy of this template.**
+  Copy this template into `docs/enhacements` and name it `YYYYMMDD-my-title.md`, where `YYYYMMDD` is the date the proposal was first drafted.
+1. **Fill out the required sections.**
+1. **Create a PR.**
+  Aim for single topic PRs to keep discussions focused.
+  If you disagree with what is already in a document, open a new PR with suggested changes.
+
+The canonical place for the latest set of instructions (and the likely source of this file) is [here](./YYYYMMDD-template.md).
+
+The `Metadata` section above is intended to support the creation of tooling around the proposal process.
+This will be a YAML section that is fenced as a code block.
+See the proposal process for details on each of these items.
+
+<!-- END Remove before PR -->
+
+## Table of Contents
+
+A table of contents is helpful for quickly jumping to sections of a proposal and for highlighting
+any additional information provided beyond the standard proposal template.
+[Tools for generating](https://github.com/ekalinin/github-markdown-toc) a table of contents from markdown are available.
+
+- [Title](#title)
+  - [Table of Contents](#table-of-contents)
+  - [Glossary](#glossary)
+  - [Summary](#summary)
+  - [Motivation](#motivation)
+    - [Goals](#goals)
+    - [Non-Goals/Future Work](#non-goalsfuture-work)
+  - [Proposal](#proposal)
+    - [User Stories](#user-stories)
+      - [Story 1](#story-1)
+      - [Story 2](#story-2)
+    - [Requirements (Optional)](#requirements-optional)
+      - [Functional Requirements](#functional-requirements)
+        - [FR1](#fr1)
+        - [FR2](#fr2)
+      - [Non-Functional Requirements](#non-functional-requirements)
+        - [NFR1](#nfr1)
+        - [NFR2](#nfr2)
+    - [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints)
+    - [Risks and Mitigations](#risks-and-mitigations)
+  - [Alternatives](#alternatives)
+  - [Upgrade Strategy](#upgrade-strategy)
+  - [Additional Details](#additional-details)
+    - [Test Plan [optional]](#test-plan-optional)
+  - [Implementation History](#implementation-history)
+
+## Glossary
+
+Refer to the [Cluster API Book Glossary](https://cluster-api.sigs.k8s.io/reference/glossary.html).
+
+If this proposal adds new terms, or defines some, make the changes to the book's glossary when in PR stage.
+
+## Summary
+
+The `Summary` section is incredibly important for producing high quality user-focused documentation such as release notes or a development roadmap.
+It should be possible to collect this information before implementation begins in order to avoid requiring implementors to split their attention between writing release notes and implementing the feature itself.
+
+A good summary is probably at least a paragraph in length.
+
+## Motivation
+
+This section is for explicitly listing the motivation, goals and non-goals of this proposal.
+
+- Describe why the change is important and the benefits to users.
+- The motivation section can optionally provide links to [experience reports](https://github.com/golang/go/wiki/ExperienceReports)
+to demonstrate the interest in a proposal within the wider Kubernetes community.
+
+### Goals
+
+- List the specific high-level goals of the proposal.
+- How will we know that this has succeeded?
+
+### Non-Goals/Future Work
+
+- What high-levels are out of scope for this proposal?
+- Listing non-goals helps to focus discussion and make progress.
+
+## Proposal
+
+This is where we get down to the nitty gritty of what the proposal actually is.
+
+- What is the plan for implementing this feature?
+- What data model changes, additions, or removals are required?
+- Provide a scenario, or example.
+- Use diagrams to communicate concepts, flows of execution, and states.
+
+[PlantUML](http://plantuml.com) is the preferred tool to generate diagrams,
+place your `.plantuml` files under `images/` and run `make diagrams` from the docs folder.
+
+### User Stories
+
+- Detail the things that people will be able to do if this proposal is implemented.
+- Include as much detail as possible so that people can understand the "how" of the system.
+- The goal here is to make this feel real for users without getting bogged down.
+
+#### Story 1
+
+#### Story 2
+
+### Requirements (Optional)
+
+Some authors may wish to use requirements in addition to user stories.
+Technical requirements should be derived from user stories, and provide a trace from
+use case to design, implementation and test case. Requirements can be prioritised
+using the MoSCoW (MUST, SHOULD, COULD, WON'T) criteria.
+
+The difference between goals and requirements is that between an executive summary
+and the body of a document. Each requirement should be in support of a goal,
+but narrowly scoped in a way that is verifiable or ideally - testable.
+
+#### Functional Requirements
+
+Functional requirements are the properties that this design should include.
+
+##### FR1
+
+##### FR2
+
+#### Non-Functional Requirements
+
+Non-functional requirements are user expectations of the solution. Include
+considerations for performance, reliability and security.
+
+##### NFR1
+
+##### NFR2
+
+### Implementation Details/Notes/Constraints
+
+- What are some important details that didn't come across above.
+- What are the caveats to the implementation?
+- Go in to as much detail as necessary here.
+- Talk about core concepts and how they releate.
+
+### Risks and Mitigations
+
+- What are the risks of this proposal and how do we mitigate? Think broadly.
+- How will UX be reviewed and by whom?
+- How will security be reviewed and by whom?
+- Consider including folks that also work outside the SIG or subproject.
+
+## Alternatives
+
+The `Alternatives` section is used to highlight and record other possible approaches to delivering the value proposed by a proposal.
+
+## Upgrade Strategy
+
+If applicable, how will the component be upgraded? Make sure this is in the test plan.
+
+Consider the following in developing an upgrade strategy for this enhancement:
+- What changes (in invocations, configurations, API use, etc.) is an existing cluster required to make on upgrade in order to keep previous behavior?
+- What changes (in invocations, configurations, API use, etc.) is an existing cluster required to make on upgrade in order to make use of the enhancement?
+
+## Additional Details
+
+### Test Plan [optional]
+
+## Implementation History
+
+- [ ] MM/DD/YYYY: Proposed idea in an issue or [community meeting]
+- [ ] MM/DD/YYYY: Compile a Google Doc following the CAEP template (link here)
+- [ ] MM/DD/YYYY: First round of feedback from community
+- [ ] MM/DD/YYYY: Present proposal at a [community meeting]
+- [ ] MM/DD/YYYY: Open proposal PR
+