Cornerstone

# 开发者指南

要想编辑或改造 Cornerstone，您将需要安装 Node.js (opens new window)。npm 包管理器随着 Node.js 附带一起安装，你可以使用它们来安装项目依赖，并且运行常用的开发任务。

# 常用任务

# 安装依赖

npm install

注意

安装/更新依赖项应该在git存储库的每次更新之后执行。如果不执行此操作，您可能会在开发过程中遇到问题。

# 运行生成

npm start

运行生成将同时创建这个库的压缩和未压缩的版本，以及它们各自的 source map 文件。

# 在每次变更后自动运行生成

npm run watch

如果要调试问题或向源代码添加新功能，可以使用此命令。

# 发布开发使用的文件服务

有很多方法运行一个简单的 HTTP 服务器。下面只举一个例，您也可以使用其它，如 python -m simplehttpserver 8080

  1. 安装 http-server 包:
npm install http-server -g

提示

有时候您可能需要使用 sudo 去执行全局安装。

  1. 运行服务器
http-server
  1. 访问 http://127.0.0.1:8080/example/index.html (opens new window) 在浏览器加载示例。

注意

要想在移动设备上访问这些，您需要运行 HTTP 服务器，然后通过电脑 IP 地址进行访问（比如：http://192.168.1.11:8080/example/index.html (opens new window)）

# 运行和调试测试用例

npm test

运行测试时，将创建一个“coverage”目录。请注意，因为它只是一个构建生成文件，所以在主代码库中不存在这个目录。通过浏览器打开“coverage/html/index.html”这个 HTML 文件（不必启用一个 HTTP 服务器），您能够查看和检查测试覆盖报告。

Istanbul Code Coverage Report

当启动了测试之后，您还可以用浏览器访问 http://0.0.0.0:9876/debug ，通过 Karma 测试程序去进行测试的调试。请注意，这个 URL 不会立即生效，因为 npm test 命令的第一步是重新构建整个库。

# 运行代码风格检测

npm run eslint

# Or include automatic fixing with:
npm run eslint-fix

# Or automatically fix 'test' directory with:
npm run eslint-fix-test

Running the commands above will check the source code for linting issues.

# Submitting changes through Pull Requests

If you have made a source code change that you think should be included in the main repository, you can contribute it back to the community by creating a Pull Request (opens new window). Please create an associated Issue (opens new window) to describe the problem you are solving / feature you are adding so the library maintainers can give you feedback on whether or not these changes are appropriate for the repository. It's possible that your bug fix / new feature would be better implemented in another library (e.g. Cornerstone Tools (opens new window)). Please ensure that all tests pass and you have run ESLint and fixed any issues before submitting a pull request.

# Development Toolchain and Specifications

Cornerstone relies on a number of open source tools, components, and free services to ensure quality and stability. We want to ensure developers can work in modern JavaScript and that end users can use the tools in both current and legacy environments.

# General

# Testing

# Documentation

# Writing tests

Here are some general notes on writing tests which may be useful:

  • Tests must be in the 'test' directory. Please try to ensure they follow the 'src' directory layout for simplicity.
  • Test file names must end in "_test.js"
  • The 'coverage_test.js' file ensures that all files are considered by Istanbul, so that code coverage reports can be used to explore the whole repository.
  • Do not convert 'function ()' to arrow functions (i.e. '=> {}') within the 'it', 'should', or 'describe' blocks or Mocha will fail to run the tests properly.

# Releasing a new version

  1. Make sure you have the latest commits from master
  2. Determine the version change you need to make based on the scope of the changes since the last release.
  3. Update the changelog (opens new window)
  • Make sure to thank any code contributors!
  1. Update the package and dependency versions in "package.json"
  2. Update the build version:
npm run version
  1. Run the build:
npm run build
  1. Commit the changes
git commit -am "Bump version <version>"
  1. Tag the commits with the version number and title
git tag -a "<version>" -m "Version <version>"
  1. Push the commit with the version number to master
git push origin master --tags
  1. Publish the release to NPM:
npm publish

# Updating Docs with gitbook

# If its your first time:

  1. Make sure you have gitbook-cli installed globally, if not, run:
npm install -g gitbook-cli
  1. Go inside the /docs folder and do:
gitbook install

# Updating files and deploying

  1. On the root folder run:
npm run docs
# It will serve the documentation on http://localhost:4000/
# with livereload
  1. Change the docs needed and make sure everything is correct
  2. In order to deploy, run:
npm run docs:deploy