From f35caeeb7dda64a42618067f4ec31962ca54ee72 Mon Sep 17 00:00:00 2001 From: xuzhonghu Date: Thu, 18 Jul 2019 15:08:03 +0800 Subject: [PATCH 1/4] add developing docs --- docs/development/development.md | 155 +++++++++++++++++++ docs/development/perepare-for-development.md | 56 +++++++ 2 files changed, 211 insertions(+) create mode 100644 docs/development/development.md create mode 100644 docs/development/perepare-for-development.md diff --git a/docs/development/development.md b/docs/development/development.md new file mode 100644 index 0000000000..bde70a060d --- /dev/null +++ b/docs/development/development.md @@ -0,0 +1,155 @@ +This document helps you get started using the Volcano code base. +If you follow this guide and find some problem, please take +a few minutes to update this file. + +- [Building the code](#building-the-code) +- [Building docker images](#building-docker-images) +- [Building a specific docker image](#building-a-specific-docker-image) +- [Building the Volcano manifests](#building-the-volcano-manifests) +- [Cleaning outputs](#cleaning-outputs) +- [Running tests](#running-tests) +- [Auto-formatting source code](#auto-formatting-source-code) +- [Running the verification](#running-the-verification) +- [Adding dependencies](#adding-dependencies) +- [About testing](#about-testing) + + +## Cloning the code + +You will need to clone the main `volcano` repo to `$GOPATH/src/volcano.sh/volcano` for +the below commands to work correctly. + +## Building the code + +To build volcano all components for your host architecture, go to +the source root and run: + +```bash +make image_bins +``` + +To build a specific component for your host architecture, go to +the source root and run `make `: + +```bash +make vc-scheduler +``` + + +## Building docker images + +Build the containers in your local docker cache: + +```bash +make images +``` + +## Building a specific docker image + +If you want to make a local change and test some component, say `vc-controllers`, you +could do: + +Under volcano.sh/volcano repo + +```bash +pwd +``` +The path should be + +```bash +.../src/volcano.sh/volcano +``` + +Set up environment variables HUB and TAG by +```bash +export HUB=docker.io/yourrepo +export TAG=citadel +``` + +Make some local change of the code, then build `vc-controllers` + +```bash +make image.vc-controllers +``` + +## Building the Volcano manifests + +Use the following command to build the deploy yaml files: + +```bash +make generate-yaml +``` + +## Cleaning outputs + +You can delete any build artifacts with: + +```bash +make clean +``` + +## Running tests + +### Running unit tests + +You can run all the available unit tests with: + +```bash +make unit-test +``` + +### Running e2e tests + +You can run all the available e2e tests with: + +```bash +make vcctl +make images +make e2e-test-kind +``` + +If you want to run e2e test in a existing cluster with volcano deployed, run the following: + +```bash +KUBECONFIG=${KUBECONFIG} go test ./test/e2e +``` + +## Auto-formatting source code + +You can automatically format the source code to follow our conventions by going to the +top of the repo and entering: + +```bash +./hack/update-gofmt.sh +``` + +## Running the verification + +You can run all the verification we require on your local repo by going to the top of the repo and entering: + +```bash +make verify +``` + +## Adding dependencies + +Volcano uses [dep](https://github.com/golang/dep) to manage its dependencies. +If you want to add or update a dependency, running: + +```bash +dep ensure -add dependency-name@version +``` + +## About testing + +Before sending pull requests you should at least make sure your changes have +passed both unit and the verification. We only merge pull requests when +**all** tests are passing. + +- Unit tests should be fully hermetic + - Only access resources in the test binary. +- All packages and any significant files require unit tests. +- Unit tests are written using the standard Go testing package. +- The preferred method of testing multiple scenarios or input is + [table driven testing](https://github.com/golang/go/wiki/TableDrivenTests) +- Concurrent unit test runs must pass. diff --git a/docs/development/perepare-for-development.md b/docs/development/perepare-for-development.md new file mode 100644 index 0000000000..ad7455124d --- /dev/null +++ b/docs/development/perepare-for-development.md @@ -0,0 +1,56 @@ +This document helps you get started developing code for Volcano. +If you follow this guide and find some problem, please take +a few minutes to update this file. + +Volcano components only have few external dependencies you +need to set up before being able to build and run the code. + +- [Setting up Go](#setting-up-go) +- [Setting up Docker](#setting-up-docker) +- [Other dependencies](#other-dependencies) +- [Setting up Kubernetes](#setting-up-kubernetes) +- [Setting up personal access token](#setting-up-a-personal-access-token) + +## Setting up Go + +All Volcano components are written in the [Go](https://golang.org) programming language. +To build, you'll need a Go development environment. If you haven't set up a Go development +environment, please follow [these instructions](https://golang.org/doc/install) +to install the Go tools. + +Volcano currently builds with Go 1.12 + +## Setting up Docker + +Istio has a Docker build system for creating and publishing Docker images. +To leverage that you will need: + +- **Docker platform:** To download and install Docker follow [these instructions](https://docs.docker.com/install/). + +- **Docker Hub ID:** If you do not yet have a Docker ID account you can follow [these steps](https://docs.docker.com/docker-id/) to create one. This ID will be used in a later step when setting up the environment variables. + + +## Setting up Kubernetes + +We require Kubernetes version 1.12 or higher. + +// TODO: add some install ways, like minikube, kind, kubeadm, etc. +// Better links to some install guides + + +### Setting up a personal access token + +This is only necessary for core contributors in order to push changes to the main repos. +You can make pull requests without two-factor authentication +but the additional security is recommended for everyone. + +To be part of the Volcano organization, we require two-factor authentication, and +you must setup a personal access token to enable push via HTTPS. Please follow +[these instructions](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) +for how to create a token. +Alternatively you can [add your SSH keys](https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/). + +### What's next? + +Once you've set up the prerequisites, continue with [Using the Code Base](./development.md) +for more details about how to build & test Volcano. \ No newline at end of file From 2681e7ff22018d638aa32c57f7271535a5cf5ff2 Mon Sep 17 00:00:00 2001 From: SrinivasChilveri Date: Thu, 18 Jul 2019 16:52:55 +0530 Subject: [PATCH 2/4] added contribute guide, community membership,code of conduct docs --- code_of_conduct.md | 76 ++++++++++ community-membership.md | 119 ++++++++++++++++ contribute.md | 142 +++++++++++++++++++ docs/development/perepare-for-development.md | 10 +- 4 files changed, 344 insertions(+), 3 deletions(-) create mode 100644 code_of_conduct.md create mode 100644 community-membership.md create mode 100644 contribute.md diff --git a/code_of_conduct.md b/code_of_conduct.md new file mode 100644 index 0000000000..65cf5ffee9 --- /dev/null +++ b/code_of_conduct.md @@ -0,0 +1,76 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq diff --git a/community-membership.md b/community-membership.md new file mode 100644 index 0000000000..11558f7744 --- /dev/null +++ b/community-membership.md @@ -0,0 +1,119 @@ + +# Volcano Community Membership + +**Note :** This document keeps changing based on the status and feedback of Volcano Community. + +This document gives a brief overview of the Volcano community roles with the requirements and responsibilities associated with them. + +| Role | Requirements | Responsibilities | Privileges | +| -----| ---------------- | ------------ | -------| +| [Member](#member) | Sponsor from 2 approvers, active in community, contributed to Volcano | Welcome and guide new contributors | Volcano GitHub organization Member | +| [Approver](#approver) | Sponsor from 2 maintainers, has good experience and knowledge of domain, actively contributed to code and review | Review and approve contributions from community members | Write access to specific packages in relevant repository | +| [Maintainer](#maintainer) | Sponsor from 2 owners, shown good technical judgement in feature design/development and PR review | Participate in release planning and feature development/maintenance | Top level write access to relevant repository. Name entry in Maintainers file of the repository | +| [Owner](#owner) | Sponsor from 3 owners, helps drive the overall Volcano project | Drive the overall technical roadmap of the project and set priorities of activities in release planning | Volcano GitHub organization Admin access | + + +**Note :** It is mandatory for all Volcano community members to follow Volcano [Code of Conduct](./code_of_conduct.md). + +## Member + +Members are active participants in the community who contribute by authoring PRs, +reviewing issues/PRs or participate in community discussions on slack/mailing list. + + +### Requirements + +- Sponsor from 2 approvers +- Enabled [two-factor authentication] on their GitHub account +- Actively contributed to the community. Contributions may include, but are not limited to: + - Authoring PRs + - Reviewing issues/PRs authored by other community members + - Participating in community discussions on slack/mailing list + - Participate in Volcano community meetings + + +### Responsibilities and privileges + +- Member of the Volcano GitHub organization +- Can be assigned to issues and PRs and community members can also request their review +- Participate in assigned issues and PRs +- Welcome new contributors +- Guide new contributors to relevant docs/files +- Help/Motivate new members in contributing to Volcano + + +## Approver + +Approvers are active members who have good experience and knowledge of the domain. +They have actively participated in the issue/PR reviews and have identified relevant issues during review. + + +### Requirements + +- Sponsor from 2 maintainers +- Member for at least 2 months +- Have reviewed good number of PRs +- Have good codebase knowledge + + +### Responsibilities and Privileges + +- Review code to maintain/improve code quality +- Acknowledge and work on review requests from community members +- May approve code contributions for acceptance related to relevant expertise +- Have 'write access' to specific packages inside a repo, enforced via bot +- Continue to contribute and guide other community members to contribute in Volcano project + +## Maintainer + +Maintainers are approvers who have shown good technical judgement in feature design/development in the past. +Has overall knowledge of the project and features in the project. + +### Requirements + +- Sponsor from 2 owners +- Approver for at least 2 months +- Nominated by a project owner +- Good technical judgement in feature design/development + +### Responsibilities and privileges + +- Participate in release planning +- Maintain project code quality +- Ensure API compatibility with forward/backward versions based on feature graduation criteria +- Analyze and propose new features/enhancements in Volcano project +- Demonstrate sound technical judgement +- Mentor contributors and approvers +- Have top level write access to relevant repository (able click Merge PR button when manual check-in is necessary) +- Name entry in Maintainers file of the repository +- Participate & Drive design/development of multiple features + +## Owner + +Owners are maintainers who have helped drive the overall project direction. +Has deep understanding of Volcano and related domain and facilitates major agreement in release planning + +### Requirements + +- Sponsor from 3 owners +- Maintainer for at least 2 months +- Nominated by a project owner +- Not opposed by any project owner +- Helped in driving the overall project + +### Responsibilities and Privileges + +- Make technical decisions for the overall project +- Drive the overall technical roadmap of the project +- Set priorities of activities in release planning +- Guide and mentor all other community members +- Ensure all community members are following Code of Conduct +- Although given admin access to all repositories, make sure all PRs are properly reviewed and merged +- May get admin access to relevant repository based on requirement +- Participate & Drive design/development of multiple features + + +**Note :** These roles are applicable only for Volcano github organization and repositories. Currently Volcano doesn't have a formal process for review and acceptance into these roles. We will come-up with a process soon. + + +[two-factor authentication]: https://help.github.com/articles/about-two-factor-authentication diff --git a/contribute.md b/contribute.md new file mode 100644 index 0000000000..228f5e7047 --- /dev/null +++ b/contribute.md @@ -0,0 +1,142 @@ + +# Welcome to Volcano! + +- [Before you get started](#before-you-get-started) + - [Code of Conduct](#code-of-conduct) + - [Community Expectations](#community-expectations) +- [Getting started](#getting-started) +- [Your First Contribution](#your-first-contribution) + - [Find something to work on](#find-something-to-work-on) + - [Find a good first topic](#find-a-good-first-topic) + - [Work on an Issue](#work-on-an-issue) + - [File an Issue](#file-an-issue) +- [Contributor Workflow](#contributor-workflow) + - [Creating Pull Requests](#creating-pull-requests) + - [Code Review](#code-review) + - [Testing](#testing) + +# Before you get started + +## Code of Conduct + +Please make sure to read and observe our [Code of Conduct](./code_of_conduct.md). + +## Community Expectations + +Volcano is a community project driven by its community which strives to promote a healthy, friendly and productive environment. +The goal of the community is to develop a volcano system which is useful for runnning high performance workloads such as AI,ML,Deep Learning Application on top of Kubernetes. To build a such volcano system at such scale requires the support of a community with similar aspirations. + +- See [Community Membership](./community-membership.md) for a list of various community roles. With gradual contributions, one can move up in the chain. + + +# Getting started + +- Read the [get started](docs/development/perepare-for-development.md) for developing code for Volcano +- Read the [setup](docs/development/development.md) for build/deploy instructions. + + +# Your First Contribution + +We will help you to contribute in different areas like filing issues, developing features, fixing critical bugs and getting your work reviewed and merged. + +If you have questions about the development process, feel free to jump into our [Slack Channel](https://github.com/volcano-sh/volcano/blob/master/slack-invitation) or join our [mailing list](https://groups.google.com/forum/#!forum/volcano-sh). + +## Find something to work on + +We are always in need of help, be it fixing documentation, reporting bugs or writing some code. +Look at places where you feel best coding practices aren't followed, code refactoring is needed or tests are missing. +Here is how you get started. + +### Find a good first topic + +There are [multiple repositories](https://github.com/volcano-sh/) within the Volcano organization. +Each repository has beginner-friendly issues that provide a good first issue. +For example, [Volcano-Issues](https://github.com/volcano-sh/volcano) has [help wanted](https://github.com/volcano-sh/volcano/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) and [good first issue](https://github.com/volcano-sh/volcano/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) labels for issues that should not need deep knowledge of the system. +We can help new contributors who wish to work on such issues. + +Another good way to contribute is to find a documentation improvement, such as a missing/broken link. + +#### Work on an issue + +When you are willing to take on an issue, you can assign it to yourself. Just reply with `/assign` or `/assign @yourself` on an issue, +then the robot will assign the issue to you and your name will present at `Assignees` list. + +### File an Issue + +While we encourage everyone to contribute code, it is also appreciated when someone reports an issue. +Issues should be filed under the appropriate Volcano sub-repository. + +*Example:* a Volcano issue should be opened to [Volcano](https://github.com/volcano-sh/volcano/issues). + +Please follow the prompted submission guidelines while opening an issue. + +# Contributor Workflow + +Please do not ever hesitate to ask a question or send a pull request. + +This is a rough outline of what a contributor's workflow looks like: + +- Create a topic branch from where to base the contribution. This is usually master. +- Make commits of logical units. +- Make sure commit messages are in the proper format (see below). +- Push changes in a topic branch to a personal fork of the repository. +- Submit a pull request to [Volcano](https://github.com/volcano-sh/volcano). +- The PR must receive an approval from two maintainers. + +## Creating Pull Requests + +Pull requests are often called simply "PR". +Volcano generally follows the standard [github pull request](https://help.github.com/articles/about-pull-requests/) process. + +In addition to the above process, a bot will begin applying structured labels to your PR. + +The bot may also make some helpful suggestions for commands to run in your PR to facilitate review. +These `/command` options can be entered in comments to trigger auto-labeling and notifications. +Refer to its [command reference documentation](https://go.k8s.io/bot-commands). + +## Code Review + +To make it easier for your PR to receive reviews, consider the reviewers will need you to: + +* follow [good coding guidelines](https://github.com/golang/go/wiki/CodeReviewComments). +* write [good commit messages](https://chris.beams.io/posts/git-commit/). +* break large changes into a logical series of smaller patches which individually make easily understandable changes, and in aggregate solve a broader issue. +* label PRs with appropriate reviewers: to do this read the messages the bot sends you to guide you through the PR process. + +### Format of the commit message + +We follow a rough convention for commit messages that is designed to answer two questions: what changed and why. +The subject line should feature the what and the body of the commit should describe the why. + +``` +scripts: add test codes for metamanager + +this add some unit test codes to imporve code coverage for metamanager + +Fixes #12 +``` + +The format can be described more formally as follows: + +``` +: + + + +