arthas/CONTRIBUTING.md

131 lines
4.9 KiB
Markdown
Raw Normal View History

2018-09-13 00:23:22 +08:00
## Issue
Welcome to use [issue tracker](https://github.com/alibaba/arthas/issues) 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](https://github.com/alibaba/arthas/tree/master/site/src/site/sphinx/en).
## Developer
2018-10-12 15:01:36 +08:00
* 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`](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`](https://github.com/alibaba/arthas/blob/master/bin/as.sh) to start Arthas, it will get the latest version under `~/.arthas/lib`;
2. when [`as-package.sh`](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.
```bash
./as.sh --use-version 3.0.5.20180919185025
```
Tip: you can use `--versions` to list all available versions.
```bash
./as.sh --versions
```
### Debug
2018-10-12 15:01:36 +08:00
* [Debug Arthas In IDEA](https://github.com/alibaba/arthas/issues/222)
### Packaging All
* Arthas is using [Sphinx](http://www.sphinx-doc.org/en/master/) to generate the static site
* `sphinx-maven-plugin` configured in [`site/pom.xml`](https://github.com/alibaba/arthas/tree/master/site)
* `sphinx-maven-plugin` executes by downloading`sphinx-binary/`
* a [bug](https://github.com/rtfd/recommonmark/issues/93) in Sphinx plugin `recommonmark`; we fix it by packaging another [version](https://github.com/hengyunabc/sphinx-binary/releases/tag/v0.4.0.1)
* when packaging the whole project (Packaging All), you need to (Only Unix/Linux/Mac supported):
```bash
./mvnw clean package -DskipTests -P full -Dsphinx.binUrl=https://github.com/hengyunabc/sphinx-binary/releases/download/v0.4.0.1/sphinx.osx-x86_64
```
---
2018-09-13 00:23:22 +08:00
## issue
欢迎在issue里对arthas做反馈分享使用技巧排查问题的经历。
* https://github.com/alibaba/arthas/issues
## 改进用户文档
2018-09-19 19:31:12 +08:00
用户文档在`site/src/site/sphinx`目录下如果希望改进arthas用户文档欢迎提交PR。
英文文档在`site/src/site/sphinx/en`目录下欢迎提交翻译PR。
2018-09-13 00:23:22 +08:00
## 开发者相关
2018-10-12 15:01:36 +08:00
* Arthas运行支持JDK6+
* 编绎Arthas要求JDK7+因为使用到了jdk7里的`java.lang.management.BufferPoolMXBean`。
2018-09-13 00:23:22 +08:00
### 安装到本地
本地开发时,推荐执行`as-package.sh`来打包会自动安装最新版本的arthas到`~/.arthas`目录里。debug时会自动使用最新版本。
2018-09-13 00:23:22 +08:00
`as.sh`在启动时,会对`~/.arthas/lib`下面的目录排序,取最新的版本。`as-package.sh`在打包时,会取`pom.xml`里的版本号,再拼接上当前时间,比如: `3.0.5.20180917161808`,这样子排序时取的就是最新的版本。
2018-12-03 11:48:04 +08:00
也可以直接 `./mvnw clean package -DskipTests`打包生成的zip在 `packaging/target/` 下面。但是注意`as.sh`启动加载的是`~/.arthas/lib`下面的版本。
2018-09-19 19:31:12 +08:00
### 启动指定版本的arthas
本地开发时,可能会产生多个版本,可以用 `--use-version` 参数来指定版本,比如
```bash
./as.sh --use-version 3.0.5.20180919185025
```
可以用`--versions`参数来列出所有版本:
```bash
./as.sh --versions
```
### Debug
2018-10-12 15:01:36 +08:00
* [Debug Arthas In IDEA](https://github.com/alibaba/arthas/issues/222)
2018-09-13 00:23:22 +08:00
### 全量打包
* arthas是用sphinx来生成静态网站
2018-12-07 11:24:05 +08:00
* 在`site/pom.xml`里配置了`sphinx-maven-plugin`
2018-09-13 00:23:22 +08:00
* `sphinx-maven-plugin`通过下载`sphinx-binary/`来执行
* sphinx配置的`recommonmark`插件有bughttps://github.com/rtfd/recommonmark/issues/93 ,因此另外打包了一个修复版本: https://github.com/hengyunabc/sphinx-binary/releases/tag/v0.4.0.1
* 全量打包时需要配置下面的参数目前只支持mac/linux
```
./mvnw clean package -DskipTests -P full -Dsphinx.binUrl=https://github.com/hengyunabc/sphinx-binary/releases/download/v0.4.0.1/sphinx.osx-x86_64
2018-09-13 00:23:22 +08:00
```
2018-12-07 11:24:05 +08:00
### Release Steps
2018-09-13 00:23:22 +08:00
2018-12-07 11:24:05 +08:00
发布release版本流程
* 修改`as.sh`里的版本
* 修改本地的maven settings.xml
* mvn release:prepare -Darguments="-DskipTests"
* mvn release:perform -Darguments="-DskipTests -P full -Dsphinx.binUrl=https://github.com/hengyunabc/sphinx-binary/releases/download/v0.4.0.1/sphinx.osx-x86_64"
* 到 https://oss.sonatype.org/ 上“Staging Repositories”然后close掉自己的再release
2018-09-13 00:23:22 +08:00