Skip to content

Commit be2acb2

Browse files
imurchieimurchie
authored
Update Contributing Docs (appium#10165)
* Update contributing docs * Fix some links and examples * Address comments
1 parent 77fe650 commit be2acb2

13 files changed

+245
-534
lines changed

‎CONTRIBUTING.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Note that no matter how you contribute, your participation is governed by our
88
### Make changes to the Appium code or docs
99

1010
Fork the project, make a change, and send a pull request! Please have a look at
11-
our [Style Guide](/docs/en/contributing-to-appium/style-guide-2.0.md) before
11+
our [Style Guide](/docs/en/contributing-to-appium/style-guide.md) before
1212
getting to work. Please make sure the unit and functional tests pass before
1313
sending a pull request; for more information on how to run tests, keep reading!
1414

‎docs/cn/contributing-to-appium/appium-from-source.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
你想从源码运行Appium并帮助修复BUG和添加功能吗？
44
真棒！只需要fork工程，添加一个修改，然后发送pull请求即可！
5-
在开始之前请阅读我们的代码风格指南（[Style Guide](style-guide-2.0.md)。
5+
在开始之前请阅读我们的代码风格指南（[Style Guide](style-guide.md)。
66
在发送pull请求前请确保通过单元和功能测试；关于如何运行测试等更多信息，请继续阅读！
77

88
首先，确保你阅读README文件且按照设置说明走。

‎docs/cn/contributing-to-appium/developers-overview.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ node.js的原生支持，Appium代码是_被移植_到ES5（JS更为广泛支持
6363
### 排查和代码风格
6464

6565
对于所有Appium的JS而言，代码外观和使用感觉同样重要。这包括样式常规，编码模式以及我们解决各种问题时使用的
66-
库。你应该熟悉我们新的[ES2015 风格指南](/docs/cn/contributing-to-appium/style-guide-2.0.md)。
66+
库。你应该熟悉我们新的[ES2015 风格指南](/docs/cn/contributing-to-appium/style-guide.md)。
6767
当转化时，Appium包将自动运行JSHint或其他lint工具，并在代码不符合我们规范的时候提供警告或错误反馈。
6868
这些工具不一定能顾全我们关心的种种风格问题，所以我们在review代码的时候也应该注意代码规范问题。这不是
6969
吹毛求疵，而是为了有一个整洁，一致并且可读的代码库。
@@ -102,7 +102,7 @@ _FORCE_LOGS=1 <command> # 显示测试运行期间的模块日志输出
102102
任何非Appium主包的发布流程都是非常简洁明了的（请注意：如果你想要发布它，你需要成为一个NPM的所有者。
103103
所有权由Appium提交者管理； 如果你对所有者有任何疑问，请联系@jlipps 或者 @imurchie）。
104104

105-
0. `rm -rf node_modules && npm install` 并运行测试以确保全新安装正常工作
105+
0. `rm -rf node_modules && rm -rf package-lock.json && npm install` 并运行测试以确保全新安装正常工作
106106
0. 根据[SemVer](http://semver.org/) 规则决定我们是否需要发布一个补丁（漏洞修复），微调（功能）或者是主要（迭代）(请参考 [how SemVer works with NPM](https://docs.npmjs.com/getting-started/semantic-versioning).
107107
0. 通过任何适当的更改和提交来更新CHANGELOG以README文件。大多数子包没有CHANGELOG。
108108
0. 通过适当的版本类型运行 `npm version <version-type>`
@@ -121,8 +121,8 @@ _FORCE_LOGS=1 <command> # 显示测试运行期间的模块日志输出
121121
因此有必要在发布过程中手动管理它。 它需要与对`package.json`的更改一起提交到GitHub。
122122

123123
0. 如果 NPM shrinkwrap JSON 文件存在，请移除.
124-
0. `rm -rf node_modules && npm install` 并运行测试以确保全新安装正常工作
125-
0. `rm -rf node_modules && npm install --production` 以获取仅production部分.
124+
0. `rm -rf node_modules && rm -rf package-lock.json && npm install` 并运行测试以确保全新安装正常工作
125+
0. `rm -rf node_modules && rm -rf package-lock.json && npm install --production` 以获取仅production部分.
126126
0. `npm shrinkwrap` 来编写新的 NPM shrinkwrap JSON 文件.
127127
0. 根据SemVer来决定我们是否需要发布一个补丁（漏洞修复），微调（功能）或者是主要（迭代）
128128
0. 用合适的新版本信息来更新`package.json`

‎docs/en/contributing-to-appium/appium-from-source.md

+86-51
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,20 @@
22

33
So you want to run Appium from source and help fix bugs and add features?
44
Great! Just fork the project, make a change, and send a pull request! Please
5-
have a look at our [Style Guide](style-guide-2.0.md) before getting to work.
5+
have a look at our [Style Guide](style-guide.md) before getting to work.
66
Please make sure the unit and functional tests pass before sending a pull
77
request; for more information on how to run tests, keep reading!
88

9-
Make sure you read and follow the setup instructions in the README first.
9+
### Node.js
10+
11+
Appium is written in JavaScript, and run with the [Node.js](https://nodejs.org/) engine. Currently
12+
version 6+ is supported. While Node.js can be installed globally on the system,
13+
a version manager is _highly_ recommended.
14+
* NVM - [https://github.com/creationix/nvm](https://github.com/creationix/nvm)
15+
* N - [https://github.com/tj/n](https://github.com/tj/n)
16+
17+
Your Node.js installation will include the [NPM](https://www.npmjs.com/) package manager, which Appium
18+
will need in order to manage dependencies. Appiums supports NPM version 3+.
1019

1120
### Setting up Appium from Source
1221

@@ -17,57 +26,43 @@ instance of an Appium server, and then run your test.
1726

1827
The quick way to get started:
1928

20-
```center
29+
```
2130
git clone https://github.com/appium/appium.git
2231
cd appium
2332
npm install
24-
gulp transpile # requires gulp, see below
25-
npm install -g authorize-ios # for ios only
26-
authorize-ios # for ios only
33+
npm run build
2734
node .
2835
```
2936

3037
### Hacking on Appium
3138

32-
Make sure you have `ant`, `maven`, `adb` installed and added to system `PATH`, also you
33-
would need the android-16 sdk (for Selendroid) and android-19 sdk installed.
34-
From your local repo's command prompt, install the following packages using the
35-
following commands (if you didn't install `node` using Homebrew, you might have
36-
to run `npm` with sudo privileges):
37-
38-
```center
39-
npm install -g mocha
40-
npm install -g gulp
41-
npm install -g gulp-cli
42-
npm install -g appium-doctor && appium-doctor --dev
39+
Install the [appium-doctor](https://github.com/appium/appium-doctor) tool, and run it to verify all of the
40+
dependencies are set up correctly (since dependencies for building Appium
41+
are different from those for simply running it):
42+
```
43+
npm install -g appium-doctor
44+
appium-doctor --dev
45+
```
46+
Install the Node.js dependencies:
47+
```
4348
npm install
44-
gulp transpile
4549
```
4650

47-
The first two commands install test and build tools (`sudo` may not be
48-
necessary if you installed node.js via Homebrew). The third command verifies
49-
that all of the dependencies are set up correctly (since dependencies for
50-
building Appium are different from those for simply running Appium) and fourth
51-
command installs all app dependencies and builds supporting binaries and test
52-
apps. The final command transpiles all the code so that `node` can run it.
53-
5451
When pulling new code from GitHub, if there are changes to `package.json` it
5552
is necessary to remove the old dependencies and re-run `npm install`:
5653

57-
```center
58-
rm -rf node_modules
59-
npm install
60-
gulp transpile
54+
```
55+
rm -rf node_modules && rm -rf package-lock.json && npm install
6156
```
6257

6358
At this point, you will be able to start the Appium server:
6459

65-
```center
60+
```
6661
node .
6762
```
6863

6964
See [the server documentation](/docs/en/writing-running-appium/server-args.md)
70-
for a full list of arguments.
65+
for a full list of command line arguments that can be used.
7166

7267
#### Hacking with Appium for iOS
7368

@@ -80,36 +75,37 @@ have to modify your `/etc/authorization` file in one of two ways:
8075
2. Run the following command which automatically modifies your
8176
`/etc/authorization` file for you:
8277

83-
```center
78+
```
8479
npm install -g authorize-ios
8580
sudo authorize-ios
8681
```
8782
8883
At this point, run:
8984
90-
```center
91-
rm -rf node-modules
92-
npm install
93-
gulp transpile
85+
```
86+
rm -rf node_modules && rm -rf package-lock.json && npm install
9487
```
9588
9689
Now your Appium instance is ready to go. Run `node .` to kick up the Appium server.
9790
9891
#### Hacking with Appium for Android
9992
93+
To work on Android, make sure you have `ant`, `maven`, and `adb` installed
94+
and added to system `PATH` environment variable. Also you would need the
95+
android-16 sdk (for `Selendroid`) and android-19+ sdk installed.
96+
From your local repo's command prompt, install/run the following:
97+
10098
Set up Appium by running:
10199
102-
```center
103-
rm -rf node-modules
104-
npm install
105-
gulp transpile
100+
```
101+
rm -rf node_modules && rm -rf package-lock.json && npm install
106102
```
107103
108104
Make sure you have one and only one Android emulator or device running, e.g.,
109105
by running this command in another process (assuming the `emulator` command is
110106
on your path):
111107
112-
```center
108+
```
113109
emulator -avd <MyAvdName>
114110
```
115111
@@ -123,12 +119,44 @@ update everything necessary. You will also need to do this when Appium bumps
123119
its version up. Prior to running `npm install` it is recommended to remove
124120
all the old dependencies in the `node_modules` directory:
125121
126-
```center
127-
rm -rf node-modules
128-
npm install
129-
gulp transpile
122+
```
123+
rm -rf node_modules && rm -rf package-lock.json && npm install
130124
```
131125
126+
### Different packages
127+
128+
Appium is made up of a number of different packages. While it is often possible
129+
to work in a single package, it is also often the case that work, whether fixing
130+
a bug or adding a new feature, requires working on multiple packages simultaneously.
131+
132+
Unfortunately the dependencies installed when running `npm install` are those that
133+
have already been published, so some work is needed to link together local development
134+
versions of the packages that are being worked on.
135+
136+
In the case where one package, `A`, depends on another package, `B`, the following steps
137+
are necessary to link the two:
138+
1. In one terminal, enter into package `B`
139+
```
140+
cd B
141+
```
142+
2. Use [NPM link](https://docs.npmjs.com/cli/link) to create symbolic link to this package
143+
```
144+
npm link
145+
```
146+
3. In another terminal, enter into package `A`
147+
```
148+
cd A
149+
```
150+
4. Use [NPM link](https://docs.npmjs.com/cli/link) to link the dependent package `B` to the development version
151+
```
152+
npm link B
153+
```
154+
155+
Now the version of `B` that `A` uses will be your local version. Remember, however, that
156+
changes made to the JavaScript will only be available when they have been transpiled, so
157+
when you are going to test from package `A`, run `npm run build` in the directory for
158+
package `B`.
159+
132160
### Running Tests
133161
134162
First, check out our documentation on [running tests in
@@ -138,16 +166,23 @@ system is set up properly for the platforms you desire to test on.
138166
Once your system is set up and your code is up to date, you can run unit tests
139167
with:
140168
141-
```center
142-
gulp once
169+
```
170+
npm run test
143171
```
144172
145173
You can run functional tests for all supported platforms (after ensuring that
146174
Appium is running in another window with `node .`) with:
147175
148-
```center
149-
gulp e2e-test
150176
```
177+
npm run e2e-test
178+
```
179+
180+
### Committing code
181+
182+
Each Appium package installs a pre-commit hook which will run the [linter](https://eslint.org/) and
183+
the unit tests before the commit is made. Any error in either of these will stop
184+
the commit from occurring.
151185
152-
Before committing code, please run `gulp once` to execute some basic tests and
153-
check your changes against code quality standards.
186+
Once code is committed and a [pull request](https://help.github.com/articles/about-pull-requests/)
187+
is made to the correct Appium respository on [GitHub](https://github.com/), Appium build system
188+
will run all of the functional tests.

‎docs/en/contributing-to-appium/dev-tools.md

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
## Appium development commands
2+
3+
Each Appium package has a number of NPM scripts that are used to automate
4+
development tasks:
5+
6+
| Task | Description |
7+
|------------------|--------------------------------------------------------|
8+
| npm run build | Transpile code into the `build` directory |
9+
| npm run lint | Runs ESLint |
10+
| npm run test | Cleans, lints, transpiles, and runs unit tests |
11+
| npm run e2e-test | Tranpiles and runs functional tests |
12+
| npm run watch | Automatically runs `test` command when code is changed |
13+
| npm run mocha | Gives access to `mocha` test runner |
14+
15+
In addition, the main Appium package has a task `npm generate-docs` which generates
16+
the command documentation.

‎docs/en/contributing-to-appium/developers-overview.md

+24-24
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ Most Appium packages have this as the default behavior when running `gulp`.
9393
It's important for all of Appium's JS to look and feel the same. This includes
9494
style conventions as well as coding patterns and which libraries we use to
9595
solve various problems. You should get familiar with our new [ES2015 Style
96-
Guide](/docs/en/contributing-to-appium/style-guide-2.0.md). When transpiling,
96+
Guide](/docs/en/contributing-to-appium/style-guide.md). When transpiling,
9797
Appium packages will automatically run ESLint or other lint tools and provide
9898
warning or error feedback if the code doesn't conform to our style. These tools
9999
are not necessarily exhaustive of the kinds of style issues we care about, so
@@ -147,12 +147,12 @@ package if you want to publish it. Ownership is managed by the Appium
147147
committers; talk to @jlipps or @imurchie if you believe you should be an owner
148148
and are not):
149149

150-
0. `rm -rf node_modules && npm install` and run tests to make sure a clean install works.
151-
0. Determine whether we have a patch (bugfix), minor (feature), or major (breaking) release according to the principles of [SemVer](http://semver.org/) (see also this explanation of [how SemVer works with NPM](https://docs.npmjs.com/getting-started/semantic-versioning)).
152-
0. Update the `CHANGELOG` and/or `README` with any appropriate changes and commit. Most subpackages don't have a `CHANGELOG`.
153-
0. Run `npm version <version-type>` with the appropriate version type.
154-
0. Push the appropriate branch to GitHub, and don't forget to include the `--tags` flag to include the tag just created by `npm version`.
155-
0. Run `npm publish` (with `--tag beta` if this isn't an official release).
150+
1. `rm -rf node_modules && rm -rf package-lock.json && npm install` and run tests to make sure a clean install works.
151+
1. Determine whether we have a patch (bugfix), minor (feature), or major (breaking) release according to the principles of [SemVer](http://semver.org/) (see also this explanation of [how SemVer works with NPM](https://docs.npmjs.com/getting-started/semantic-versioning)).
152+
1. Update the `CHANGELOG` and/or `README` with any appropriate changes and commit. Most subpackages don't have a `CHANGELOG`.
153+
1. Run `npm version <version-type>` with the appropriate version type.
154+
1. Push the appropriate branch to GitHub, and don't forget to include the `--tags` flag to include the tag just created by `npm version`.
155+
1. Run `npm publish` (with `--tag beta` if this isn't an official release).
156156

157157
For the main Appium packages, all the above steps must be taken, but with
158158
several changes. One reason is that for the main package we use NPM shrinkwrap
@@ -175,20 +175,20 @@ checked in to GitHub along with changes to `package.json`. With npm 5+ there is
175175
also a `package-lock.json` file produced. During the shrinkwrap process this is
176176
converted into the `npm-shrinkwrap.json` file.
177177

178-
0. Remove the NPM shrinkwrap and package-lock JSON files if they exists.
179-
0. `rm -rf node_modules && npm install` and run tests to make sure a clean install works.
180-
0. Determine whether we have a `patch` (bugfix), `minor` (feature), or `major` (breaking) release according to the principles of SemVer.
181-
0. Update `package.json` with the appropriate new version.
182-
0. Update the CHANGELOG/README with appropriate changes and submit for review as a PR, along with shrinkwrap and `package.json` changes. Wait for it to be merged, then pull it into the release branch.
183-
0. `rm -rf node_modules && npm install --production` to get just the production dependencies.
184-
0. `npm shrinkwrap` to write the new NPM shrinkwrap JSON file, and commit this file.
185-
0. Create a tag of the form `v<version>` on the release branch (usually a minor branch like `1.5` or `1.4`), with: `git tag -a v<version>`, e.g., `git tag -a v1.5.0`. This is not necessary for beta versions.
186-
0. Push the tag to upstream: `git push --tags <remote> <branch>`
187-
0. Install dev dependencies (or at least `gulp` and `appium-gulp-plugins`), and undo the changes to the NPM shrinkwrap JSON file (e.g., `git checkout -- npm-shrinkwrap.json`).
188-
0. Run `npm publish` (with `--tag beta` if this isn't an official release).
189-
0. Remove the NPM shrinkwrap JSON file from Git and push the changes
190-
0. Update the docs at appium.io. Check out the appium.io repo from github, check out the `gh-pages` branch and pull latest. Run `rake publish`.
191-
0. Create a new release on GitHub: go to `https://github.com/appium/appium/releases/tag/v<VERSION>` and hit "Edit Tag". Make the release name `<VERSION>` (e.g., `2.0.5`), then paste in the changelog (but not the changelog header for this version). If it's a beta release, mark as pre-release.
192-
0. Create a new post on discuss.appium.io announcing the release. Post it in the "News" category. Paste in the changelog and any choice comments. Pin it and unpin the previous release post.
193-
0. Begin process of releasing `appium-desktop`.
194-
0. Notify @jlipps to so he can tweet a link to the discuss post.
178+
1. Remove the NPM shrinkwrap and package-lock JSON files if they exists.
179+
1. `rm -rf node_modules && npm install` and run tests to make sure a clean install works.
180+
1. Determine whether we have a `patch` (bugfix), `minor` (feature), or `major` (breaking) release according to the principles of SemVer.
181+
1. Update `package.json` with the appropriate new version.
182+
1. Update the CHANGELOG/README with appropriate changes and submit for review as a PR, along with shrinkwrap and `package.json` changes. Wait for it to be merged, then pull it into the release branch.
183+
1. `rm -rf node_modules && npm install --production` to get just the production dependencies.
184+
1. `npm shrinkwrap` to write the new NPM shrinkwrap JSON file, and commit this file.
185+
1. Create a tag of the form `v<version>` on the release branch (usually a minor branch like `1.5` or `1.4`), with: `git tag -a v<version>`, e.g., `git tag -a v1.5.0`. This is not necessary for beta versions.
186+
1. Push the tag to upstream: `git push --tags <remote> <branch>`
187+
1. Install dev dependencies (or at least `gulp` and `appium-gulp-plugins`), and undo the changes to the NPM shrinkwrap JSON file (e.g., `git checkout -- npm-shrinkwrap.json`).
188+
1. Run `npm publish` (with `--tag beta` if this isn't an official release).
189+
1. Remove the NPM shrinkwrap JSON file from Git and push the changes
190+
1. Update the docs at appium.io. Check out the appium.io repo from github, check out the `gh-pages` branch and pull latest. Run `rake publish`.
191+
1. Create a new release on GitHub: go to `https://github.com/appium/appium/releases/tag/v<VERSION>` and hit "Edit Tag". Make the release name `<VERSION>` (e.g., `2.0.5`), then paste in the changelog (but not the changelog header for this version). If it's a beta release, mark as pre-release.
192+
1. Create a new post on discuss.appium.io announcing the release. Post it in the "News" category. Paste in the changelog and any choice comments. Pin it and unpin the previous release post.
193+
1. Begin process of releasing `appium-desktop`.
194+
1. Notify @jlipps to so he can tweet a link to the discuss post.

‎docs/en/contributing-to-appium/gulp.md

-15
This file was deleted.

0 commit comments

Comments
 (0)