From b52b096f0988240ce00f7b97e4b9432c23d8e685 Mon Sep 17 00:00:00 2001 From: Siyu Wang Date: Thu, 31 Mar 2022 12:18:07 +0800 Subject: [PATCH] Add contributing docs (#29) Signed-off-by: Siyu Wang --- .github/workflows/ci.yaml | 6 +- .github/workflows/license.yml | 1 + CONTRIBUTING.md | 132 +++++++++++++++++++ README.md | 2 +- docs/proposals/YYYYMMDD-template.md | 191 ++++++++++++++++++++++++++++ 5 files changed, 329 insertions(+), 3 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/proposals/YYYYMMDD-template.md diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 2ed361450..427f40257 100644 --- a/.github/workflows/ci.yaml +++ b/.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) diff --git a/.github/workflows/license.yml b/.github/workflows/license.yml index 37d85f1c6..181f677c5 100644 --- a/.github/workflows/license.yml +++ b/.github/workflows/license.yml @@ -2,6 +2,7 @@ name: License on: push: branches: + - main - master - release-* workflow_dispatch: {} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..e531866e0 --- /dev/null +++ b/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//.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/.git` using the following two commands: + +```bash +git remote add upstream https://github.com/koordinator-sh/.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 +git fetch upstream +git checkout main +git rebase upstream/main +``` + +Create a new branch: + +```bash +git checkout -b +``` + +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. diff --git a/README.md b/README.md index dc577d122..4db24def3 100644 --- a/README.md +++ b/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 diff --git a/docs/proposals/YYYYMMDD-template.md b/docs/proposals/YYYYMMDD-template.md new file mode 100644 index 000000000..ab29d0cb9 --- /dev/null +++ b/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. + + +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. + + + +## 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 +