Skip to content

Latest commit

 

History

History
170 lines (104 loc) · 6.14 KB

CONTRIBUTING.md

File metadata and controls

170 lines (104 loc) · 6.14 KB

Issue

Welcome to use issue tracker to give us :bowtie::

  • feedbacks - what you would like to have;
  • usage tips - what usages you have found splendid;
  • experiences - how you use Arthas to do effective troubleshooting;

Documentation

Welcome PR to further improve English documentation.

Online Tutorials

Please refer to README.MD at tutorials/katacoda

Developer

  • Arthas runtime supports JDK6+
  • To build Arthas requires JDK7+, because of the source code import JDK7 classes, such as java.lang.management.BufferPoolMXBean.

Local Installation

Recommend to use as-package.sh to package, which will auto-install the latest Arthas to local ~/.arthas and when debugging, Arthas will auto-load the latest version.

F.Y.I

  1. when using as.sh to start Arthas, it will get the latest version under ~/.arthas/lib;
  2. when as-package.sh packaging, it will get the version from pom.xml and suffix it with the current timestamp e.g. 3.0.5.20180917161808.

You can also use ./mvnw clean package -DskipTests to package and generate a zip under packaging/target/ but remember when as.sh starts, it load the version under ~/.arthas/lib.

Start Arthas in specified version

When there are several different version, you can use --use-version to specify the version of Arthas to start your debug.

./as.sh --use-version 3.0.5.20180919185025

Tip: you can use --versions to list all available versions.

./as.sh --versions

Debug

Packaging All

  • Arthas is using Sphinx to generate the static site

  • sphinx-maven-plugin configured in site/pom.xml

  • sphinx-maven-plugin executes by downloadingsphinx-binary/

  • when packaging the whole project (Packaging All), you need to execute:

    ./mvnw clean package -DskipTests -P full

Issue

欢迎在issue里对arthas做反馈,分享使用技巧,排查问题的经历。

改进用户文档

用户文档在site/src/site/sphinx目录下,如果希望改进arthas用户文档,欢迎提交PR。

英文文档在site/src/site/sphinx/en目录下,欢迎提交翻译PR。

改进在线教程

请参考tutorials/katacoda下的说明

开发者相关

  • Arthas运行支持JDK6+
  • 编译Arthas要求JDK7+,因为使用到了jdk7里的java.lang.management.BufferPoolMXBean

安装到本地

本地开发时,推荐执行as-package.sh来打包,会自动安装最新版本的arthas到~/.arthas目录里。debug时会自动使用最新版本。

as.sh在启动时,会对~/.arthas/lib下面的目录排序,取最新的版本。as-package.sh在打包时,会取pom.xml里的版本号,再拼接上当前时间,比如: 3.0.5.20180917161808,这样子排序时取的就是最新的版本。

也可以直接 ./mvnw clean package -DskipTests打包,生成的zip在 packaging/target/ 下面。但是注意as.sh启动加载的是~/.arthas/lib下面的版本。

启动指定版本的arthas

本地开发时,可能会产生多个版本,可以用 --use-version 参数来指定版本,比如

./as.sh --use-version 3.0.5.20180919185025

可以用--versions参数来列出所有版本:

./as.sh --versions

Debug

全量打包

  • arthas是用sphinx来生成静态网站

  • site/pom.xml里配置了sphinx-maven-plugin

  • sphinx-maven-plugin通过下载sphinx-binary/来执行

  • 全量打包时,需要配置下面的参数:

    ./mvnw clean package -DskipTests -P full
    

当 sphinx-maven-plugin 下载出错时,可以用下面的方式

https://github.com/trustin/sphinx-binary/releases 下载对应版本的二进制文件,并在本地加上可执行权限。例如:

wget https://github.com/hengyunabc/sphinx-binary/releases/download/v0.4.0.1/sphinx.osx-x86_64 -o /tmp/sphinx.osx-x86_64
chmod +x /tmp/sphinx.osx-x86_64
./mvnw clean package -DskipTests -P full -Dsphinx.binUrl=file:/tmp/sphinx.osx-x86_64

Release Steps

发布release版本流程:

  • 修改as.sh里的版本,最后修改日期, Bootstrap.java里的版本,Dockerfile里的版本

  • 修改本地的maven settings.xml

  • mvn clean deploy -DskipTests -P full -P release

    如果在下载 sphinx-binary 出错,参考上面的 全量打包 的说明。

  • https://oss.sonatype.org/ 上,“Staging Repositories”然后close掉自己的,再release

  • 发布后,可以到这里查看是否同步到仓库里了: https://repo1.maven.org/maven2/com/taobao/arthas/arthas-packaging/

  • 发布完maven仓库之后,需要到阿里云的仓库里检查是否同步,有可能有延时

    比如下载地址: https://maven.aliyun.com/repository/public/com/taobao/arthas/arthas-packaging/3.x.x/arthas-packaging-3.x.x-bin.zip

  • 打上tag,push tag到仓库上

  • 需要更新 gh-pages 分支下面的 arthas-boot.jar/math-game.jar/as.sh ,下载 doc.zip,解压覆盖掉文档的更新

  • 需要更新docker镜像,push新的tag:https://hub.docker.com/r/hengyunabc/arthas/tags?page=1&ordering=last_updated

    以 3.1.0 版本为例:

    docker build . --build-arg ARTHAS_VERSION=3.1.0 -t hengyunabc/arthas:3.1.0
    docker tag hengyunabc/arthas:3.1.0  hengyunabc/arthas:latest
    docker push hengyunabc/arthas:3.1.0
    docker push hengyunabc/arthas:latest
    
    docker build .  --build-arg ARTHAS_VERSION=3.1.0 -f Dockerfile-No-Jdk -t hengyunabc/arthas:3.1.0-no-jdk
    docker push hengyunabc/arthas:3.1.0-no-jdk
    
  • 更新README.md,比如增加了新命令,要加上说明,更新wiki的链接

  • 更新release页面的 issue信息,修改信息等

  • 更新内部的版本