Skip to content

Commit

Permalink
udpate instructions and documents (#909)
Browse files Browse the repository at this point in the history 
* Update README.md

Signed-off-by: Haining Henry Zhang <[email protected]>

Improve and update the documentation

* Update CONTRIBUTING.md

Signed-off-by: Haining Henry Zhang <[email protected]>
Improve the content.
  • Loading branch information
@hainingzhang
hainingzhang authored Aug 7, 2023
1 parent 0924ea2 commit c43a768
Show file tree
Hide file tree
Showing 2 changed files with 40 additions and 38 deletions.
49 changes: 25 additions & 24 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
# Contributing
# Contribution

## Welcome
KubeFATE is developed in the open, and is constantly being improved by our **users, contributors, and maintainers**. It is because of you that we can bring great software to the community.
KubeFATE is an open-source project, continuously advancing thanks to the active involvement of our **users, contributors, and maintainers**. Together, we strive to create a remarkable platform that benefits everyone involved.

This guide provides information on filing issues and guidelines for open source contributors. **Please leave comments / suggestions if you find something is missing or incorrect.**

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.
Before making any contributions to this repository, we kindly request that you initiate a discussion with the repository owners. You can do this by creating an issue, sending an email, or employing any other suitable communication method. This approach ensures alignment and collaboration, helping us better understand the proposed change and maintain the repository's overall coherence.

Please note we have a code of conduct, please follow it in all your interactions with the project.
Kindly be aware that we maintain a Code of Conduct, and we request your adherence to it in all your interactions with the project. Your cooperation in upholding a respectful and inclusive environment is greatly appreciated.

## Contribute Workflow
PR are always welcome, even if they only contain small fixes like typos or a few lines of codes. If there will be a significant effort, please:
1. document it as a proposal;
## Contribution Workflow
Pull requests (PRs) are always welcome, even if they only contain small fixes like typos or a few lines of codes. If there will be a significant effort, please:
1. Document it as a proposal;
2. PR it to https://github.com/FederatedAI/KubeFATE/tree/master/proposals;
3. Get a discussion by creating [feature request issues](https://github.com/FederatedAI/KubeFATE/issues/new?assignees=&labels=&template=feature_request.md&title=) and refer to the proposal;
4. Implement the feature when the proposal got 2+ maintainer approved;
4. Implement the feature once the proposal receives approval from two or more maintainers.
5. PR to `KubeFATE` **master** branch.

### Fork and clone
Expand Down Expand Up @@ -45,7 +45,7 @@ Branch from the updated master branch:
git checkout -b my_feature master
```

### Keep sync with upstream
### Keep in sync with upstream
Once your branch gets out of sync with the kubefate/master branch, use the following commands to update:
```
git checkout my_feature
Expand Down Expand Up @@ -120,7 +120,7 @@ KubeFATE is applying Apache license, please include a short license header at th
```
_Note: "VMware, Inc." in the above example can be changed to the name of your organization or simplily "The KubeFATE Authors"._

### Commit
### Commit your Code
As KubeFATE has integrated the [DCO (Developer Certificate of Origin)](https://probot.github.io/apps/dco/) check tool, contributors are required to sign-off that they adhere to those requirements by adding a Signed-off-by line to the commit messages. Git has even provided a -s command line option to append that automatically to your commit messages, please use it when you commit your changes.
```
$ git commit -s -m 'This is my commit message'
Expand All @@ -133,29 +133,30 @@ git push --force-with-lease $user my_feature
The commit message should follow the convention on How to Write a Git Commit Message. Be sure to include any related GitHub issue references in the commit message.
```

### Push and Create PR
When ready for review, push your branch to your fork repository on github.com:
### Create a PR
When ready for review, push your branch to your forked repository on github.com:
```
git push --force-with-lease $user my_feature
```
Then visit your fork at https://github.com/$user/KubeFATE and click the `Compare & Pull Request` button next to your `my_feature` branch to create a new pull request (PR). The PR should:
1. Ensure all unit test passed;
2. Ensure any install or build dependencies are removed before the end of the layer when doing a build;
3. The tittle of PR should hightlight what it solve briefly. The description of PR should refer to all the issues that it addresses. Ensure to put a reference to issues (such as `Close #xxx` and `Fixed #xxx`) Please refer to the [PULL_REQUEST_TEMPLATE.md](https://github.com/FederatedAI/KubeFATE/blob/master/PULL_REQUEST_TEMPLATE.md).
Then visit your fork at https://github.com/$user/KubeFATE and click on the `Compare & Pull Request` button next to your `my_feature` branch to create a new pull request (PR). The PR should:
1. Ensure all unit tests have passed;
2. Ensure any installatioin or build dependencies are removed before the final layer when doing a build;
3. The title of PR should hightlight what it solve briefly. The description of PR should refer to all the issues that it addresses. Ensure to put a reference to issues (such as `Close #xxx` and `Fixed #xxx`) Please refer to the [PULL_REQUEST_TEMPLATE.md](https://github.com/FederatedAI/KubeFATE/blob/master/PULL_REQUEST_TEMPLATE.md).

Once your pull request has been opened it will be assigned to one or more reviewers. Those reviewers will do a thorough code review, looking for correctness, bugs, opportunities for improvement, documentation and comments, and style.
Once your pull request has been opened, it will be assigned to one or more reviewers. Those reviewers will do a thorough code review, looking for correctness, bugs, opportunities for improvement, documentation and comments, and style.

Commit changes made in response to review comments to the same branch on your fork.

### Automated Testing
Once your pull request has been opened, KubeFATE will run two CI pipelines against it.
When you submit a pull request to KubeFATE, our automated testing process comes into action with two CI pipelines running against it:

1. In the Github action, your source code will be checked via golint, go vet and go race that makes sure the code is readable, safe and correct. Also all of unit tests will be triggered via go test against the pull request.
* If any failure in `github action checks`, you need to figure out whether it is introduced by your commits.
* If the coverage dramatic decline, you need to commit unit test to coverage your code.
2. In the Jenkins CI, the E2E test will be triggered. The pipeline is about to build and install a FATE cluster and run the federated learning workload.

## No-code way contributing
To contribute to the KubeFATE project, there are many ways beyond coding.
## Non-coding contribution
At KubeFATE, we value and welcome contributions in various forms beyond coding. There are numerous ways you can make a meaningful impact on the project and help us grow.

### Submitting an issue
It is a great way to contribute to KubeFATE by reporting an issue. Well-written and complete bug reports are always welcome! Please open an issue on GitHub and follow the template to fill in the required information.
Expand All @@ -172,9 +173,9 @@ Be sure to include the steps to reproduce the problem if applicable. It can help

Another very appreciated way of contribution is submitting an issue of `feature request`. Make sure you are selecting the right template to draft it. Make sure you describing the problem to solve clearly. And it is also very important to stress the value of the feature requested, it is the important basis of our decision and work arrangement.

### Documenting (includes Wikis)
Help us update, correct, add documents is greatly appreciated! It will help others better use KubeFATE and build a better community. Some documents to guide a beginner on how to use KubeFATE are also welcome and can be added to Wikis. Contact us if there are some documents or articles you can contribute.
### Documentation (includeing Wikis)
We highly value your assistance in updating, correcting, and adding documents. Your contributions are immensely appreciated, as they will not only enhance the usage of KubeFATE but also foster a stronger community. We welcome any documents that can guide beginners on how to utilize KubeFATE, and these can be seamlessly added to our Wikis. If you have any documents or articles to contribute, please don't hesitate to contact us. Your support will be of great value in our collective effort to build a better and more accessible platform.

### Advocate and educate
### Advocate and Educate

We are welcome any articles or blog posts to advocate the KubeFATE project or educate others on how to use KubeFATE for federated learning lifecycle management. If you can let us know the links to the articles or blog posts, we can gather them to the Wiki and help promote them to the community.
We encourage the submission of articles or blog posts that advocate for the KubeFATE project or educate readers on how to effectively use KubeFATE for federated learning lifecycle management. If you have any such valuable resources, please share the links with us, and we will gladly compile them into our Wiki and promote them within the community. Your contributions play a vital role in spreading awareness and knowledge about KubeFATE, enabling us to build a stronger and more supportive community together.
29 changes: 15 additions & 14 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,34 +1,35 @@
**Note**: The `master` branch is constantly in an *unstable* or *even broken* state during development. Please use [releases](https://github.com/FederatedAI/KubeFATE/releases) instead of the `master` branch in order to get a stable version.
**Note**: The `master` branch undergoes frequent changes and can be *unstable* or even *broken* during development. To obtain a stable version, we recommend using the [releases](https://github.com/FederatedAI/KubeFATE/releases) instead of the `master` branch.


[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
# Overview
Federated learning involves multiple parties to collaboratively train a machine learning model, therefore it is usually based on a distributed system. KubeteFATE operationalizes federated learning workloads using cloud native technologies such as containers and Kubernetes. KubeFATE enables federated learning tasks to run across public, private and hybrid cloud environments.

[FATE](https://github.com/FederatedAI/FATE) (Federated AI Technology Enabler) is an open-source project to provide a secure computing framework to support the federated AI ecosystem. It implements secure computation protocols based on homomorphic encryption and secure multi-party computation (MPC). It supports federated learning architectures and secure computation of various machine learning algorithms, including logistic regression, tree-based algorithms, deep learning and transfer learning.

KubeFATE supports the deployment of FATE via Docker Compose and Kubernetes. We recommend installing a development environment of FATE via Docker Compose, and a production environment via Kubernetes.
KubeFATE facilitates the deployment of FATE using both Docker Compose and Kubernetes. For a development environment of FATE, we recommend utilizing Docker Compose, while for a production environment, Kubernetes is the preferred option.

## Getting Involved
* For any frequently asked questions, you can check in [FAQ](https://github.com/FederatedAI/KubeFATE/wiki/KubeFATE#faqs).
* To find answers to frequently asked questions, please refer to the [FAQ](https://github.com/FederatedAI/KubeFATE/wiki/KubeFATE#faqs) section.
* Please report bugs by submitting [issues](https://github.com/FederatedAI/KubeFATE/issues).
* Submit contributions using [pull requests](https://github.com/FederatedAI/KubeFATE/pulls)
* Submit contributions using [pull requests](https://github.com/FederatedAI/KubeFATE/pulls).

## Project Structure
```
KubeFATE
|-- docker-deploy
|-- k8s-deploy
```
`docker-deploy`: The principle is to quickly set up an federated learning environment . Docker Compose can deploy FATE components on a single host. By using Docker Compose, FATE can be set up for environments of multiple parties which are collaborating in a federated manner. Please refer to [Docker Compose Deployment](./docker-deploy/README.md) for more details.
`docker-deploy`: The primary objective is to swiftly establish a federated learning environment. Docker Compose allows for the deployment of FATE components on a single host. Leveraging Docker Compose, FATE can be configured for multi-party environments, facilitating collaborative federated setups. For further information, kindly refer to the [Docker Compose Deployment](./docker-deploy/README.md) documentation.

`k8s-deploy`: The deployment approach is designed for a production environment. It is designed with flexibility to operate FATE clusters in different environments.
`k8s-deploy`: The deployment approach is specifically tailored for production environments, providing a robust and scalable solution. Its design offers exceptional flexibility, enabling seamless operation of FATE clusters across various environments with ease and efficiency.

### Major features of KubeFATE k8s-deploy
* Provide a single executable binary for initializing and managing FATE clusters.
* Full life cycle management of FATE clusters, including deploying a new FATE cluster, querying an existing FATE cluster, destroying a given FATE cluster, etc.
* Deliver an executable binary that simplifies the initialization and management of FATE clusters.
* Provide the full life cycle management of FATE clusters, including deploying a new FATE cluster, querying an existing FATE cluster, destroying a given FATE cluster, etc.
* Support customized deployment.
* Support an instance of KubeFATE to manage multiple instances of FATE deployments.
* Provide cluster management service with RESTful APIs.
* Efficiently manage multiple instances of FATE deployments simultaneously.
* Offer a cluster management service with RESTful APIs.

For more details, please refer to [Kubernetes Deployment](./k8s-deploy/README.md).

Expand All @@ -47,10 +48,10 @@ To build the container image of KubeFATE service, a Docker environment is needed
$ make docker-build
```

## Specifying an image repository
By default, the installation script pulls the images from [Docker Hub](https://hub.docker.com/u/federatedai) during the deployment.
* For docker compose mode, modify the .env file to specify the image registry.
* For K8s mode, check this [offical doc](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/).
## Specifying an image repository (registry)
By default, the installation script pulls the images from [Docker Hub](https://hub.docker.com/u/federatedai) during the deployment process.
* For docker compose mode, modify the `.env` file to specify the image registry.
* For K8s mode, check out this [offical document](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/).

## License
[Apache License 2.0](https://github.com/FederatedAI/FATE/blob/master/LICENSE)

0 comments on commit c43a768

Please sign in to comment.