Starwhale 开源贡献指南

参与贡献

Starwhale 非常欢迎来自开源社区的贡献，包括但不限于以下方式：

• 描述使用过程中的遇到的问题
• 提交Feature Request
• 参与Slack和Github Issues讨论
• 参与Code Review
• 改进文档和示例程序
• 修复程序Bug
• 增加Test Case
• 改进代码的可读性
• 开发新的Features
• 编写Enhancement Proposal

可以通过以下方式参与开发者社区，获取最新信息和联系Starwhale开发者：

• Slack
• Github Issues
• Twitter
• Email: developer@starwhale.ai

Starwhale社区使用Github Issues来跟踪问题和管理新特性的开发。可以选择"good first issue"或"help wanted"标签的issue，作为参与开发Starwhale的起点。

Starwhale资源列表

• 主页
• Starwhale Cloud
• 官方文档
• Github Repo
• Github Docs Repo
• Python Package
• Docker镜像：Docker Hub，ghcr.io, Starwhale Hosted
• Helm Charts

代码基本结构

核心目录组织及功能说明如下：

• client：swcli和Python SDK的实现，使用Python3编写，对应Starwhale Standalone Instance的所有功能。
  • api：Python SDK的接口定义和实现。
  • cli：Command Line Interface的入口点。
  • base：Python 端的一些基础抽象。
  • core：Starwhale 核心概念的实现，包括Dataset、Model、Runtime、Project、Job、Evaluation等。
  • utils：Python 端的一些工具函数。
• console：前端的实现，使用React + TypeScript编写，对应Starwhale Cloud Instance的Web UI。
• server：Starwhale Controller的实现，使用Java编写，对应Starwhale Cloud Instance的后端API。
• docker：Helm Charts，绝大多数Docker Image的Dockerfile等。
• docs：Starwhale官方文档。
• example：示例程序，包含MNIST等例子。
• scripts：一些Bash和Python脚本，用来进行E2E测试和软件发布等。

Fork&Clone Starwhale仓库

您需要fork Starwhale仓库代码并clone到本机，

• Fork Starwhale仓库：Fork Starwhale Github Repo，更多使用详情可参考：Fork a repo

• 安装Git-LFS：Git LFS

  git lfs install

• Clone代码到本地

  git clone https://github.com/${your username}/starwhale.git

搭建针对Standalone Instance的本地开发环境

Standalone Instance采用Python编写，当要修改Python SDK和swcli时，需要进行相应的环境搭建。

Standalone本地开发环境前置条件

• OS：Linux或macOS
• Python：3.7~3.11
• Docker：>=19.03 (非必须，当调试dockerize、生成docker image或采用docker为载体运行模型任务时需要)
• Python隔离环境：Python venv 或 virtualenv 或 conda等都可以，用来构建一个隔离的Python环境

从源码进行安装

基于上一步clone到本地的仓库目录：starwhale，并进入到client子目录：

cd starwhale/client

使用Conda创建一个Starwhale开发环境，或者使用venv/virtualenv等创建：

conda create -n starwhale-dev python=3.8 -y
conda activate starwhale-dev

安装Client包及依赖到starwhale-dev环境中：

make install-sw
make install-dev-req

输入swcli --version命令，观察是否安装成功，开发环境的swcli版本是 0.0.0.dev0 ：

❯ swcli --version
swcli, version 0.0.0.dev0

❯ swcli --version
/home/username/anaconda3/envs/starwhale-dev/bin/swcli

本地修改代码

现在可以对Starwhale代码进行修改，不需要重复安装(make install-sw命令)就能在当前starwhale-dev环境是测试cli或sdk。Starwhale Repo中设置了 .editorconfig 文件，大部分IDE或代码编辑器会自动支持该文件的导入，采用统一的缩进设置。

执行代码检查和测试

在 starwhale 目录中操作，会执行单元测试、client的e2e测试、mypy检查、flake8检查和isort检查等。

make client-all-check

搭建针对Cloud Instance的本地开发环境

Cloud Instance的后端采用Java编写，前端采用React+TypeScript编写，可以按需搭建相应的开发环境。

搭建前端Console开发环境

搭建后端Server开发环境

• 开发语言：Java
• 项目构建工具：Maven
• 开发框架：Spring Boot+Mybatis
• 测试框架：Junit5（其中mock框架为mockito，断言部分使用hamcrest，数据库、web服务等模拟使用Testcontainers）
• 代码检查：使用maven插件 maven-checkstyle-plugin

Server开发环境前置条件

• OS：Linux、macOS或Windows
• JDK: >=11
• Docker：>=19.03
• Maven：>=3.8.1
• Mysql：>=8.0.29
• Minio
• Kubernetes cluster/Minikube（如果没有k8s集群，可以使用Minikube作为开发调试时的备选方案）

修改代码并增加单测

现在可以进入到相应模块，对server端的代码进行修改、调整。其中业务功能代码位置为src/main/java，单元测试目录为src/test/java。

执行代码检查和单元测试

cd starwhale/server
mvn clean package

本地部署服务

• 前置服务

  • Minikube（可选，无k8s集群时可使用此服务，安装方式可见：Minikube）

    minikube start
    minikube addons enable ingress
    minikube addons enable ingress-dns

  • Mysql

    docker run --name sw-mysql -d \
    -p 3306:3306 \
    -e MYSQL_ROOT_PASSWORD=starwhale \
    -e MYSQL_USER=starwhale \
    -e MYSQL_PASSWORD=starwhale \
    -e MYSQL_DATABASE=starwhale \
    mysql:latest

  • Minio

    docker run --name minio -d
    -p 9000:9000  --publish 9001:9001
    -e MINIO_DEFAULT_BUCKETS='starwhale'
    -e MINIO_ROOT_USER="minioadmin"
    -e MINIO_ROOT_PASSWORD="minioadmin"
    bitnami/minio:latest

• 打包server程序

  若部署server端时，需要把前端同时部署上，可先执行前端部分的构建命令，然后执行'mvn clean package'，则会自动将已编译好的前端文件打包进来。

  使用如下命令对程序进行打包：

  cd starwhale/server
  mvn clean package

• 指定server启动所需的环境变量

  # Minio相关配置
  export SW_STORAGE_ENDPOINT=http://${Minio IP，默认为127.0.0.1}:9000
  export SW_STORAGE_BUCKET=${Minio bucket，默认为starwhale}
  export SW_STORAGE_ACCESSKEY=${Minio accessKey，默认为starwhale}
  export SW_STORAGE_SECRETKEY=${Minio secretKey，默认为starwhale}
  export SW_STORAGE_REGION=${Minio region，默认为local}
  # kubernetes配置
  export KUBECONFIG=${.kube配置文件所在路径}\.kube\config
  
  export SW_INSTANCE_URI=http://${Server服务所在机器IP}:8082
  # Mysql相关配置
  export SW_METADATA_STORAGE_IP=${Mysql IP，默认为127.0.0.1}
  export SW_METADATA_STORAGE_PORT=${Mysql port，默认为3306}
  export SW_METADATA_STORAGE_DB=${Mysql dbname，默认为starwhale}
  export SW_METADATA_STORAGE_USER=${Mysql user，默认为starwhale}
  export SW_METADATA_STORAGE_PASSWORD=${user password，默认为starwhale}

• 部署server服务

  使用IDE或如下方式部署均可。

  java -jar controller/target/starwhale-controller-0.1.0-SNAPSHOT.jar

• 功能调试

  这里有两种方式对修改的功能进行调试：

  • 使用swagger-ui进行接口调试，访问 /swagger-ui/index.html找到对应的api即可。
  • 或直接在ui访问，进行相应功能的调试（前提是打包时已经按说明将前端代码进行了提前构建）