Nail/fission-src
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improving contributing docs (#1726)

Browse Source 
Improved contributing docs, added DO logo in sponsors.
This commit is contained in:
Vishal
2020-09-23 13:38:39 +05:30
committed by GitHub
parent 2b805fc7ca
commit 778f047376
2 changed files with 260 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+223 -29
View File
@@ -1,45 +1,239 @@
# Contributing to Fission
### Thank you!
Thanks for helping make Fission better😍!
Thank you for taking the time and effort to contribute to Fission!
There are many areas we can use contributions - ranging from code, documentation, feature proposals, issue triage, samples, and content creation.
First, please read the [code of conduct](CODE_OF_CONDUCT.md). By
participating, you're expected to uphold this code.
First, please read the [code of conduct](CODE_OF_CONDUCT.md). By participating, you're expected to uphold this code.
### Choose something to work on
Table of Contents
=================
The easiest way to start is to look at existing
[issues](https://github.com/fission/fission/issues) and see if there's
something there that you'd like to work on.
* [Choose something to work on](#choose-something-to-work-on)
* [Get Help.](#get-help)
* [Contributing - building & deploying](#contributing---building--deploying)
* [Prequisite](#prequisite)
* [Getting Started](#getting-started)
* [Use Skaffold with Kind/K8S Cluster to build and deploy](#use-skaffold-with-kindk8s-cluster-to-build-and-deploy)
* [Validating Installation](#validating-installation)
* [Understanding code structure](#understanding-code-structure)
* [cmd](#cmd)
* [pkg](#pkg)
* [Charts](#charts)
* [Environments](#environments)
Also, if you're familiar with a language that we don't support today,
adding an environment for a new language is a good task to take on.
Take a look at the Python environment as an example.
# Choose something to work on
If you're interested in working on something that doesn't have an
existing issue, feel free to file a new one.
* The easiest way to start is to look at existing [issues](https://github.com/fission/fission/issues) and see if there's something there that you'd like to work on. You can filter issues with label "[Good first issue](https://github.com/fission/fission/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)" which are relatively self sufficient issues and great for first time contributors.
- If you are going to pick up an issue, it would be good to add a comment stating the intention.
- If the contribution is a big change/new feature, please raise an issue and discuss the needs, design in the issue in detail.
There's plenty of stuff to do. If you need help choosing something to
work on, we'll be happy to suggest something depending on your
interests.
* For contributing a new Fission environment, please check the [environments repo](https://github.com/fission/environments)
### Talk to people
* For contributing a new Keda Connector, please check the [Keda Connectors repo](https://github.com/fission/keda-connectors)
At any point, from thinking about contributing to merging your
changes, please feel free to reach out to us! We're more than happy
to talk.
If you choose a big chunk of work that involves design changes to
Fission, please talk to us while planning the change; that way we can
all be on the same page before you invest too much work into it.
### Get Help.
Do reach out on Slack or Twitter and we are happy to help.
* Drop by the [slack channel](http://slack.fission.io).
* Say hi on [twitter](https://twitter.com/fissionio).
### Contribution Howto
* Fork this github repo
* Make a branch in your fork
* Commit your changes to that branch
* Create a pull request
# Contributing - building & deploying
## Pre-requisite
- You'll need the `go` compiler and tools installed. Currently version 1.12.x of Go is needed.
- You'll also need [docker](https://docs.docker.com/install) for building images locally.
- You will need a Kubernetes cluster and you can use one of options from below.
- [Minikube](https://github.com/kubernetes/minikube)
- [Kind](https://kind.sigs.k8s.io/)
- Cluster in cloud such as GKE (Google Kubernetes Engine cluster)/ EKS (Elastic Kubernetes Service)/ AKS (Azure Kubernetes Service)
- Kubectl and Helm installed.
- [Skaffold](https://skaffold.dev/docs/install/) for local development workflow to make it easier to build and deploy Fission.
- And of course some basic concepts of Fission such as environment, function are good to be aware of!
## Getting Started
Get the code locally and after you have made changes - you can verify formatting and other basic checks.
```sh
# Clone the repo
$ git clone https://github.com/fission/fission.git $GOPATH/src/github.com/fission/fission
$ cd $GOPATH/src/github.com/fission/fission
$ go mod vendor
# Run checks on your changes
$ ./hack/verify-gofmt.sh
$ ./hack/verify-govet.sh
```
### Use Skaffold with Kind/K8S Cluster to build and deploy
You should bring up Kind/Minikube cluster or if using a cloud provider cluster then Kubecontext should be pointing to appropriate cluster.
* For building & deploying to Cloud Provider K8S cluster such as GKE/EKS/AKS:
```
$ skaffold config set default-repo vishalbiyani // (vishalbiyani - should be your registry/Dockerhub handle)
$ skaffold run
```
* For building & deploying to Kind cluster use Kind profile
```
$ kind create cluster
$ kubectl create ns fission
$ skaffold run -p kind
```
## Validating Installation
If you are using Helm, you should see release installed:
```
helm list
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
fission fission 1 2020-05-19 16:31:46.947562 +0530 IST success fission-all-1.11.0 1.11.0
```
Also you should see the Fission services deployed and running:
```
$ kubectl get pods -nfission
NAME READY STATUS RESTARTS AGE
buildermgr-6f778d4ff9-dqnq5 1/1 Running 0 6h9m
controller-d44bd4f4d-5q4z5 1/1 Running 0 6h9m
executor-557c68c6fd-dg8ld 1/1 Running 0 6h9m
influxdb-845548c959-2954p 1/1 Running 0 6h9m
kubewatcher-5784c454b8-5mqsk 1/1 Running 0 6h9m
logger-bncqn 2/2 Running 0 6h9m
mqtrigger-kafka-765b674ff-jk5x9 1/1 Running 0 6h9m
mqtrigger-nats-streaming-797498966c-xgxmk 1/1 Running 3 6h9m
nats-streaming-6bf48bccb6-fmmr9 1/1 Running 0 6h9m
router-db76576bd-xxh7r 1/1 Running 0 6h9m
storagesvc-799dcb5bdf-f69k9 1/1 Running 0 6h9m
timer-7d85d9c9fb-knctw 1/1 Running 0 6h9m
```
## Understanding code structure
### cmd
Cmd package is entrypoint for all runtime components and also has Dockerfile for each component. The actual logic here will be pretty light and most of logic of each component is in `pkg` (Discussed later)
| Component | Runtime Component |Used in|
| :------------- |:------------- |:-|
| fetcher | Docker Image |Environments|
| fission-bundle | Docker Image |Binary for all components|
| fission-cli | CLI Binary |CLI by user|
| preupgradechecks | Docker Image |Pre-install upgrade|
```
.
cmd
├── fetcher
│   ├── Dockerfile.fission-fetcher
│   ├── app
│   └── main.go
├── fission-bundle
│   ├── Dockerfile.fission-bundle
│   ├── main.go
│   └── mqtrigger
├── fission-cli
│   ├── app
│   ├── fission-cli
│   └── main.go
└── preupgradechecks
├── Dockerfile.fission-preupgradechecks
├── main.go
└── preupgradechecks.go
```
**fetcher** : is a very lightweight component and all of related logic is in fetcher package itself. Fetcher helps in fetching and uploading code and in specializing environments.
**fission-bundle** : is a component which is a single binary for all components. Based on arguments you pass to fission-bundle - it becomes that component. For ex.
```
/fission-bundle --controllerPort "8888" # Runs Controller
/fission-bundle --kubewatcher --routerUrl http://router.fission # Runs Kubewatcher
```
So most serverside components running on server side are fission-bundle binary wrapped in container and used with different arguments. Various arguments and environment variables are passed from manifests/helm chart
**fission-cli** : is the cli used by end user to interact Fission
**preupgradechecks** : is again a small independent component to do pre-install upgrade tasks.
### pkg
Pkg is where most of core components and logic reside. The structure is fairly self-explanatory for example all of executor related functionality will be in executor package and so on.
```
.
├── pkg
│   ├── apis
│   ├── builder
│   ├── buildermgr
│   ├── cache
│   ├── canaryconfigmgr
│   ├── controller
│   ├── crd
│   ├── error
│   ├── executor
│   ├── fetcher
│   ├── fission-cli
│   ├── generator
│   ├── info
│   ├── kubewatcher
│   ├── logger
│   ├── mqtrigger
│   ├── plugin
│   ├── publisher
│   ├── router
│   ├── storagesvc
│   ├── throttler
│   ├── timer
│   └── utils
```
### Charts
Fission currently has two charts - and we reccommend using fission-all for development.
```
.
├── charts
│   ├── README.md
│   ├── fission-all
│   └── fission-core
```
### Environments
Each of runtime environments is in fission/environments repo and fairly independent. If you are enhancing or creating a new environment - most likely you will end up making changes in that repo.
```
.
├── environments
│   ├── binary
│   ├── dotnet
│   ├── dotnet20
│   ├── go
│   ├── jvm
│   ├── nodejs
│   ├── perl
│   ├── php7
│   ├── python
│   ├── ruby
│   └── tensorflow-serving
```
README.md
+37 -35
View File
@@ -20,7 +20,21 @@ language-specific parts are isolated in something called
_environments_ (more below). Fission currently supports NodeJS, Python, Ruby, Go,
PHP, Bash, and any Linux executable, with more languages coming soon.
# Performance: 100msec cold start
Table of Contents
=================
* [Fission: Serverless Functions for Kubernetes](#fission-serverless-functions-for-kubernetes)
* [Performance: 100msec cold start](#performance-100msec-cold-start)
* [Kubernetes is the right place for Serverless](#kubernetes-is-the-right-place-for-serverless)
* [Getting Started](#getting-started)
* [Learn More](#learn-more)
* [Contributing](#contributing)
* [Get Help & Community Meeting](#get-help--community-meeting)
* [Official Releases](#official-releases)
* [Sponsors](#sponsors)
* [Licensing](#licensing)
## Performance: 100msec cold start
Fission maintains a pool of "warm" containers that each contain a
small dynamic loader. When a function is first called,
@@ -28,7 +42,7 @@ i.e. "cold-started", a running container is chosen and the function is
loaded. This pool is what makes Fission fast: cold-start latencies
are typically about 100msec.
# Kubernetes is the right place for Serverless
## Kubernetes is the right place for Serverless
We're built on Kubernetes because we think any non-trivial app will
use a combination of serverless functions and more conventional
@@ -39,70 +53,58 @@ Building on Kubernetes also means that anything you do for operations
on your Kubernetes cluster — such as monitoring or log
aggregation — also helps with ops on your Fission deployment.
# Getting started and documentation
## Fission Concepts
Visit [concepts](https://docs.fission.io/docs/concepts/) for more details.
## Documentations
You can learn more about Fission and get started from [Fission Docs](https://docs.fission.io/docs).
* See the [installation guide](https://docs.fission.io/docs/installation/) for installing and running Fission.
* See the [troubleshooting guide](https://docs.fission.io/docs/trouble-shooting/) for debugging your functions and Fission installation.
## Usage
## Getting Started
```bash
# Add the stock NodeJS env to your Fission deployment
$ fission env create --name nodejs --image fission/node-env
# A javascript one-liner that prints "hello world"
$ curl https://raw.githubusercontent.com/fission/fission/master/examples/nodejs/hello.js > hello.js
# Upload your function code to fission
$ fission function create --name hello --env nodejs --code hello.js
# Map GET /hello to your new function
$ fission route create --method GET --url /hello --function hello
# Create a function with a javascript one-liner that prints "hello world"
$ fission function create --name hello --env nodejs --code https://raw.githubusercontent.com/fission/fission/master/examples/nodejs/hello.js
# Run the function. This takes about 100msec the first time.
$ fission function test --name hello
Hello, world!
```
# Contributing
## Learn More
## Building Fission
See the [compilation guide](https://docs.fission.io/docs/contributing/).
* Understand [Fission Concepts](https://docs.fission.io/docs/concepts/).
* See the [installation guide](https://docs.fission.io/docs/installation/) for installing and running Fission.
* You can learn more about Fission and get started from [Fission Docs](https://docs.fission.io/docs).
* See the [troubleshooting guide](https://docs.fission.io/docs/trouble-shooting/) for debugging your functions and Fission installation.
## Contributing
Check out the [contributing guide](contributing.md).
## Get Help & Community Meeting
## Contact
Fission is a project by [many contributors](https://github.com/fission/fission/graphs/contributors).
Reach us on [slack](https://join.slack.com/t/fissionio/shared_invite/enQtOTI3NjgyMjE5NzE3LTllODJiODBmYTBiYWUwMWQxZWRhNDhiZDMyN2EyNjAzMTFiYjE2Nzc1NzE0MTU4ZTg2MzVjMDQ1NWY3MGJhZmE) or [twitter](https://twitter.com/fissionio).
## Community Meeting
A regular community meeting takes place every other Thursday at 09:00 AM PT (Pacific Time). [Convert to your local timezone](http://www.thetimezoneconverter.com/?t=09:00&tz=PT%20%28Pacific%20Time%29).
Meeting Link: https://zoom.us/j/413921817
The meeting agenda for next meeting and notes from past meetnigs are maintained in [this document](https://docs.google.com/document/d/1E-xw4KJgka4sUpETHxr9BJBYntzrtxlAN_CE3Wt8kws). You are welcome to join to discuss direction of project, design and implementation reviews and general questions about project etc.
# Official Releases
## Official Releases
Official releases of Fission can be found on [the releases page](https://github.com/fission/fission/releases).
Please note that it is strongly recommended that you use official releases of Fission, as unreleased versions from
the master branch are subject to changes and incompatibilities that will not be supported in the official releases.
Builds from the master branch can have functionality changed and even removed at any time without compatibility support
and without prior notice.
# Sponsors
The following companies, organizations, and individuals support Fission's ongoing maintenance and development.
Become a sponsor to get your logo on our README on Github with a link to your site.
## Sponsors
The following companies, organizations, and individuals support Fission's ongoing maintenance and development. If you are using/contributing to Fission, we would be happy to list you here, please raise a Pull request.
<p>
<a href="https://infracloud.io/"><img src="https://fission.io/sponsors/infracloud.png" alt="InfraCloud" height="70"></a>
<a href="https://srcmesh.com/"><img src="https://fission.io/sponsors/srcmesh.png" alt="Srcmesh" height="70"></a>
<a href="https://www.digitalocean.com/?utm_medium=opensource&utm_source=fissionio">
<img src="https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/PoweredByDO/DO_Powered_by_Badge_blue.svg" width="201px">
</a>
</p>
# Licensing