arthas/CONTRIBUTING.md

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.

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

• Debug Arthas In IDEA

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做反馈，分享使用技巧，排查问题的经历。

• https://github.com/alibaba/arthas/issues

改进用户文档

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

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

开发者相关

• 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

• Debug Arthas In IDEA

全量打包

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

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

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

• sphinx配置的recommonmark插件有bug：https://github.com/rtfd/recommonmark/issues/93 ，因此另外打包了一个修复版本： https://github.com/hengyunabc/sphinx-binary/releases/tag/v0.4.0.1

• 全量打包时，需要配置下面的参数：

  ./mvnw clean package -DskipTests -P full -Dsphinx.binUrl=https://github.com/hengyunabc/sphinx-binary/releases/download/v0.4.0.1/sphinx.osx-x86_64
  

Release Steps

发布release版本流程：

• 修改as.sh里的版本

• 修改本地的maven settings.xml

• mvn release:prepare -Darguments="-DskipTests"

• mvn release:perform -Darguments="-DskipTests -P full

  如果在下载 https://github.com/trustin/sphinx-binary/releases/download/v0.7.1/sphinx.osx-x86_64 时有问题，可以先下载到本地，然后用 file:/tmp/sphinx.osx-x86_64 的方式指定

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

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

• 需要更新 gh-pages 分支下面的 arthas-boot.jar/arthas-demo.jar/as.sh

• 需要更新docker镜像，push新的tag

  以 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