Skip to content

Commit 91ba05e

Browse files
jmjoyjmjoy
authored
Add compile and release docs. (#10)
1 parent 144a02b commit 91ba05e

5 files changed

Lines changed: 287 additions & 13 deletions

File tree

‎docs/en/contribution/compiling.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Compiling project
2+
3+
This document will help you compile and build the package file.
4+
5+
Prepare PHP and Rust environments.
6+
7+
## Install PHP Environment
8+
9+
For Debian user:
10+
11+
```shell
12+
sudo apt install php-cli php-dev
13+
```
14+
15+
For MacOS user:
16+
17+
```shell
18+
brew install php
19+
```
20+
21+
## Install Rust Environment
22+
23+
Install Rust globally.
24+
25+
```shell
26+
export RUSTUP_HOME=/opt/rustup
27+
export CARGO_HOME=/opt/cargo
28+
29+
curl https://sh.rustup.rs -sSf | sudo -E sh -s -- --no-modify-path
30+
sudo ln -s $CARGO_HOME/bin/rustup /usr/local/bin/rustup
31+
sudo ln -s $CARGO_HOME/bin/rustc /usr/local/bin/rustc
32+
sudo ln -s $CARGO_HOME/bin/cargo /usr/local/bin/cargo
33+
```
34+
35+
## Install requirement
36+
37+
For Debian user:
38+
39+
```shell
40+
sudo apt install gcc make libclang protobuf-compiler
41+
```
42+
43+
For MacOS user:
44+
45+
```shell
46+
brew install protobuf
47+
```
48+
49+
## Build and install Skywalking PHP Agent
50+
51+
* If you clone codes from https://github.com/apache/skywalking-php
52+
53+
```shell
54+
git clone --recursive https://github.com/apache/skywalking-php.git
55+
cd skywalking-php
56+
57+
phpize
58+
./configure
59+
make
60+
sudo make install
61+
```
62+
63+
* If you download package tar from https://skywalking.apache.org/downloads/
64+
65+
```shell
66+
sudo pecl install skywalking_agent-x.y.z.tgz
67+
```
68+
69+
The extension file `skywalking_agent.so` is generated in the php extension folder, get it by run `php-config --extension-dir`.

‎docs/en/contribution/release-agent.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# Apache SkyWalking PHP Agent release guide
2+
3+
If you're a committer, you can learn how to release SkyWalking SDK in The Apache Way and start the voting process by
4+
reading this document.
5+
6+
## Requirements
7+
8+
- Rust(rustc)
9+
- Cargo
10+
- PHP(php, php-config)
11+
- Pecl
12+
- GPG
13+
- shasum
14+
15+
## Add your GPG public key
16+
17+
1. Add your GPG public key into the [SkyWalking GPG KEYS](https://dist.apache.org/repos/dist/release/skywalking/KEYS)
18+
file. If you are a committer, use your Apache ID and password to log in this svn, and update the file. **Don't
19+
override the existing file.**(Notice, only PMC member could update this file)
20+
2. Upload your GPG public key to the public GPG site, such as [MIT's site](http://pgp.mit.edu:11371/). This site should
21+
be in the Apache maven staging repository checklist.
22+
23+
## Draft a new release
24+
25+
Open [Create a new release](https://github.com/apache/skywalking-php/releases/new) page, choose the tag, and click the `Generate release notes` button, then copy the generated text to local `/tmp/notes.txt`.
26+
27+
## Test your settings and package
28+
29+
```shell
30+
## Make sure local compiling passed
31+
> cargo build
32+
33+
## Create package.xml from package.xml.tpl
34+
> cargo run -p scripts --release -- create-package-xml --version x.y.z --notes "`cat /tmp/notes.txt`"
35+
36+
## Create local package. The skywalking_agent-x.y.z.tgz should be found in project root
37+
> pecl package
38+
```
39+
40+
## Sign the package
41+
42+
Tag the commit ID of this release as v`x.y.z`.
43+
44+
After set the version in `Cargo.toml` with the release number, package locally. Then run the following commands to sign
45+
your package.
46+
47+
```shell
48+
> export RELEASE_VERSION=x.y.z
49+
50+
## The package should be signed by your Apache committer mail.
51+
> gpg --armor --detach-sig skywalking_agent-{$RELEASE_VERSION}.tgz
52+
53+
> shasum -a 512 skywalking_agent-{$RELEASE_VERSION}.tgz > skywalking_agent-{$RELEASE_VERSION}.tgz.sha512
54+
```
55+
56+
After these, the source tar with its signed asc and sha512 are ready.
57+
58+
## Upload to Apache SVN and tag a release
59+
60+
1. Use your Apache ID to log in to `https://dist.apache.org/repos/dist/dev/skywalking/php`.
61+
2. Create a folder and name it by the release version and round, such as: `x.y.z`
62+
3. Upload tar ball, asc, sha512 files to the new folder.
63+
64+
## Call a vote in dev
65+
66+
Call a vote in `dev@skywalking.apache.org`
67+
68+
```
69+
Mail title: [VOTE] Release Apache SkyWalking version PHP x.y.z
70+
71+
Mail content:
72+
Hi All,
73+
This is a call for vote to release Apache SkyWalking PHP version x.y.z.
74+
75+
Release Candidate:
76+
77+
* https://dist.apache.org/repos/dist/dev/skywalking/php/x.y.z/
78+
* sha512 checksums
79+
- xxxxxxxx skywalking_agent-x.y.z.tgz
80+
81+
Release Tag :
82+
83+
* (Git Tag) vx.y.z
84+
85+
Release CommitID :
86+
87+
* https://github.com/apache/skywalking-php/tree/{commit-id}
88+
89+
Keys to verify the Release Candidate :
90+
91+
* https://dist.apache.org/repos/dist/release/skywalking/KEYS
92+
93+
Guide to build the release from source :
94+
95+
* https://github.com/apache/skywalking-php/blob/master/docs/en/contribution/compiling.md
96+
97+
Voting will start now (Date) and will remain open for at least 72
98+
hours, Request all PMC members to give their vote.
99+
[ ] +1 Release this package.
100+
[ ] +0 No opinion.
101+
[ ] -1 Do not release this package because....
102+
```
103+
104+
## Vote Check
105+
106+
The voting process is as follows:
107+
108+
1. All PMC member votes are +1 binding, and all other votes are +1 but non-binding.
109+
1. If you obtain at least 3 (+1 binding) votes with more +1 than -1 votes within 72 hours, the release will be approved.
110+
111+
## Publish the release
112+
113+
1. Move source codes tar and distribution packages to `https://dist.apache.org/repos/dist/release/skywalking/`.
114+
115+
```shell
116+
> export SVN_EDITOR=vim
117+
> svn mv https://dist.apache.org/repos/dist/dev/skywalking/php/x.y.z https://dist.apache.org/repos/dist/release/skywalking/php
118+
....
119+
enter your apache password
120+
....
121+
```
122+
123+
2. Pecl publish package on [skywalking_agent](https://pecl.php.net/package/skywalking_agent).
124+
125+
Make sure you have a PECL account, and list in `package.tpl.xml` as `<developer>`,
126+
or reach `private@skywalking.apache.org` if you are a committer/PMC but not listed.
127+
128+
You can request a PECL account via <https://pecl.php.net/account-request.php>.
129+
130+
3. Add an release event, update download and doc releases on the SkyWalking website.
131+
132+
4. Add the new release on [ASF addrelease site](https://reporter.apache.org/addrelease.html?skywalking).
133+
134+
5. Remove the old releases on `https://dist.apache.org/repos/dist/release/skywalking/php/{previous-version}`.
135+
136+
## Send a release announcement
137+
138+
Send ANNOUNCE email to `dev@skywalking.apache.org`, `announce@apache.org`. The sender should use the Apache email
139+
account.
140+
141+
```txt
142+
Mail title: [ANNOUNCE] Apache SkyWalking PHP x.y.z released
143+
144+
Mail content:
145+
Hi all,
146+
147+
SkyWalking PHP Agent provides the native tracing abilities for PHP project.
148+
149+
SkyWalking: APM (application performance monitor) tool for distributed systems,
150+
especially designed for microservices, cloud native and container-based (Docker, Kubernetes, Mesos) architectures.
151+
152+
This release contains a number of new features, bug fixes and improvements compared to
153+
version a.b.c(last release). The notable changes since x.y.z include:
154+
155+
(Highlight key changes)
156+
1. ...
157+
2. ...
158+
3. ...
159+
160+
Apache SkyWalking website:
161+
http://skywalking.apache.org/
162+
163+
Downloads:
164+
http://skywalking.apache.org/downloads/
165+
166+
Twitter:
167+
https://twitter.com/ASFSkyWalking
168+
169+
SkyWalking Resources:
170+
- GitHub: https://github.com/apache/skywalking
171+
- Issue: https://github.com/apache/skywalking/issues
172+
- Mailing list: dev@skywalkiing.apache.org
173+
174+
175+
- Apache SkyWalking Team
176+
```

‎docs/en/setup/service-agent/php-agent/README.md‎

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,28 +4,34 @@
44
2. Build from source
55
3. Configure php.ini
66

7-
## Build from source
7+
## Requirements
8+
9+
For Debian-base OS:
810

911
```shell script
10-
sudo apt install gcc make rust libclang
12+
sudo apt install gcc make cargo libclang protobuf-compiler
1113
```
1214

13-
```shell script
14-
git clone --recursive https://github.com/apache/skywalking-php.git
15+
## Install from pecl.net
1516

16-
cd skywalking-php
17+
```shell script
18+
sudo pecl install skywalking_agent
19+
```
1720

18-
# Optional, specify if php isn't installed globally.
19-
# export PHP_CONFIG=<Your path of php-config>
21+
## Build & install from source
2022

21-
# Build libskywalking_agent.so.
22-
make build
23+
```shell script
24+
git clone --recursive https://github.com/apache/skywalking-php.git
25+
cd skywalking-php
2326

24-
# Install to php extension dir.
25-
sudo make install
27+
phpize
28+
./configure
29+
make
30+
make install
2631
```
2732

2833
## Configure php.ini
34+
2935
```ini
3036
[skywalking]
3137
extension=skywalking_agent.so
@@ -50,4 +56,4 @@ skywalking_agent.skywalking_version = 8
5056

5157
# Skywalking worker threads, 0 will auto set as the cpu core size.
5258
# skywalking_agent.worker_threads = 3
53-
```
59+
```

‎docs/en/setup/service-agent/php-agent/Supported-list.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Supported SAPI, extension and library
2+
3+
The following plugins provide the distributed tracing capability.
4+
5+
## Supported SAPI
6+
7+
* PHP-FPM
8+
9+
## Support PHP extension
10+
11+
* [cURL](https://www.php.net/manual/en/book.curl.php#book.curl)
12+
13+
## Support PHP library

‎docs/menu.yml‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,4 +15,14 @@
1515

1616
catalog:
1717
- name: "PHP Agent Setup"
18-
path: "/en/setup/service-agent/php-agent/readme"
18+
path: "/en/setup/service-agent/php-agent/readme"
19+
- name: "Plugins"
20+
catalog:
21+
- name: "Supported SAPI, extension and library"
22+
path: "/en/setup/service-agent/php-agent/Supported-list"
23+
- name: "Contribution"
24+
catalog:
25+
- name: "Compiling Guidance"
26+
path: "/en/contribution/compiling/"
27+
- name: "PHP Agent Release Guidance"
28+
path: "/en/contribution/release-agent/"

0 commit comments

Comments
 (0)