From 013df9a60d9c60377fa2a4c7e9442e1dab8ce118 Mon Sep 17 00:00:00 2001 From: Patrick Cozzi Date: Tue, 27 Feb 2018 15:50:32 -0500 Subject: [PATCH 1/2] Start of Cesium -> CesiumJS renames --- README.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index fe5a753125c7..ce1a30e57d48 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,11 @@ [![Build Status](https://travis-ci.org/AnalyticalGraphicsInc/cesium.svg?branch=master)](https://travis-ci.org/AnalyticalGraphicsInc/cesium)  [![Docs](https://img.shields.io/badge/docs-online-orange.svg)](http://cesiumjs.org/tutorials.html) -Cesium is a JavaScript library for creating 3D globes and 2D maps in a web browser without a plugin. It uses WebGL for hardware-accelerated graphics, and is cross-platform, cross-browser, and tuned for dynamic-data visualization. +CesiumJS is a JavaScript library for creating 3D globes and 2D maps in a web browser without a plugin. It uses WebGL for hardware-accelerated graphics, and is cross-platform, cross-browser, and tuned for dynamic-data visualization. http://cesiumjs.org/ -### Get Started ### +### :rocket: Get Started ### Visit the [Downloads page](http://cesiumjs.org/downloads.html) or use the npm module: ``` @@ -20,17 +20,21 @@ Have questions? Ask them on the [forum](http://cesiumjs.org/forum.html). Interested in contributing? See [CONTRIBUTING.md](CONTRIBUTING.md). -### Mission ### +### :snowflake: Mission ### Our mission is to create the leading 3D globe and map for static and time-dynamic content, with the best possible performance, precision, visual quality, platform support, community, and ease of use. -### License ### +### :green_book: License ### -[Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.html). Cesium is free for both commercial and non-commercial use. +[Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0.html). CesiumJS is free for both commercial and non-commercial use. -We appreciate attribution by including the Cesium logo and link in your app. +### :earth_americas: Where Does the 3D Content Come From? ### -### Featured Demos ### +CesiumJS can stream 3D content such as terrain, imagery, and 3D Tiles from the commercial [Cesium ion](https://cesium.com/blog/2018/03/01/hello-cesium-ion/) +platform and other content sources. You are free to use any combination of content sources with CesiumJS you please, +but using Cesium ion helps support CesiumJS development. :heart: + +### :clap: Featured Demos ###

  @@ -46,7 +50,7 @@ We appreciate attribution by including the Cesium logo and link in your app.  

-### Demos ### +### :clap: Demos ###

  From 2d02f6d690111456a6fdcd57f021df8862cc7bc5 Mon Sep 17 00:00:00 2001 From: Patrick Cozzi Date: Tue, 27 Feb 2018 16:53:45 -0500 Subject: [PATCH 2/2] More Cesium -> CesiumJS --- CONTRIBUTING.md | 23 +++--- CONTRIBUTORS.md | 2 +- .../Contributors/BuildGuide/README.md | 6 +- .../Contributors/CodeReviewGuide/README.md | 14 ++-- .../Contributors/CodingGuide/README.md | 4 +- .../Contributors/CommittersGuide/README.md | 2 +- .../Contributors/DocumentationGuide/README.md | 12 +-- Documentation/Contributors/README.md | 8 +- .../Contributors/TestingGuide/README.md | 82 +++++++++---------- .../Contributors/VSCodeGuide/README.md | 26 +++--- .../Contributors/WebStormGuide/README.md | 4 +- LICENSE.md | 14 ++-- README.md | 6 +- package.json | 4 +- 14 files changed, 105 insertions(+), 102 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 389152a7b2cb..f728c5fb676d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -Thanks for contributing to Cesium. You rock! Are you +Thanks for contributing to CesiumJS. You rock! Are you * [submitting an issue](#submitting-an-issue), * [getting started contributing](#getting-started-contributing), or @@ -10,7 +10,7 @@ To ensure an inclusive community, contributors and users in the Cesium community If you have a question, do not submit an issue; instead, search the [Cesium forum](http://cesiumjs.org/forum.html). The forum is very active and there are years of informative archives, often with answers from the core Cesium team. If you do not find an answer to your question, start a new thread and you'll likely get a quick response. -If you think you've found a bug in Cesium, first search the [issues](https://github.com/AnalyticalGraphicsInc/cesium/issues). If an issue already exists, please add a comment expressing your interest and any additional information. This helps us prioritize issues. +If you think you've found a bug in CesiumJS, first search the [issues](https://github.com/AnalyticalGraphicsInc/cesium/issues). If an issue already exists, please add a comment expressing your interest and any additional information. This helps us prioritize issues. If a related issue does not exist, submit a new one. Please be concise and include as much of the following information as is relevant: * Minimum amount of sample code (and data) shared through [Sandcastle](http://cesiumjs.org/Cesium/Apps/Sandcastle/index.html?src=Hello%20World.html&label=Showcases) using a [GitHub gist](http://cesiumjs.org/2016/04/14/Share-Sandcastle-Examples-Easily-with-GitHub-Gists/). @@ -22,9 +22,9 @@ If a related issue does not exist, submit a new one. Please be concise and incl # Getting Started Contributing -Everyone is welcome to contribute to Cesium! +Everyone is welcome to contribute to CesiumJS! -In addition to contributing core Cesium code, we appreciate many types of contributions: +In addition to contributing core CesiumJS code, we appreciate many types of contributions: * Being active on the [Cesium forum](http://cesiumjs.org/forum.html) by answering questions and providing input on Cesium's direction. * Showcasing your Cesium apps on the [demos page](http://cesiumjs.org/demos.html) or writing a guest post blog on the [Cesium blog](http://cesiumjs.org/blog.html). To do either, contact [Sarah Chow](http://cesiumjs.org/team/SarahChow.html), schow@agi.com. @@ -33,7 +33,7 @@ In addition to contributing core Cesium code, we appreciate many types of contri * Triaging issues. Browse the [issues](https://github.com/AnalyticalGraphicsInc/cesium/issues) and comment on issues that are no longer reproducible or on issues which you have additional information. * Creating ecosystem projects for [glTF](https://github.com/KhronosGroup/glTF/issues/456), [CZML](https://github.com/AnalyticalGraphicsInc/cesium/wiki/CZML-Guide), and [3D Tiles](https://github.com/AnalyticalGraphicsInc/3d-tiles). -For ideas for Cesium code contributions, see: +For ideas for CesiumJS code contributions, see: * issues labeled [beginner](https://github.com/AnalyticalGraphicsInc/cesium/labels/beginner) and * issues labeled [roadmap](https://github.com/AnalyticalGraphicsInc/cesium/labels/roadmap). @@ -55,26 +55,27 @@ Before we can merge a pull request, we require a signed Contributor License Agre * [individuals](Documentation/Contributors/CLAs/individual-cla-agi-v1.0.txt) and * [corporations](Documentation/Contributors/CLAs/corporate-cla-agi-v1.0.txt). -This only needs to be completed once, and enables contributions to all of the projects under the [Analytical Graphics Inc](https://github.com/AnalyticalGraphicsInc) organization, including Cesium. The CLA ensures you retain copyright to your contributions, and provides us the right to use, modify, and redistribute your contributions using the [Apache 2.0 License](LICENSE.md). +This only needs to be completed once, and enables contributions to all of the projects under the [Analytical Graphics Inc](https://github.com/AnalyticalGraphicsInc) organization, including CesiumJS. The CLA ensures you retain copyright to your contributions, and provides us the right to use, modify, and redistribute your contributions using the [Apache 2.0 License](LICENSE.md). Please email a completed CLA with all fields filled in to [cla@agi.com](mailto:cla@agi.com). Related questions are also welcome. ## Pull Request Guidelines -Our code is our lifeblood so maintaining Cesium's high code quality is important to us. +Our code is our lifeblood so maintaining CesiumJS's high code quality is important to us. -* Review the [Contributor Guides](Documentation/Contributors/README.md). In addition to Cesium-specific topics, they contain a lot of general software development best practices. -* If this is your first contribution to Cesium, add your name to [CONTRIBUTORS.md](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/CONTRIBUTORS.md). +* Review the [Contributor Guides](Documentation/Contributors/README.md). In addition to CesiumJS-specific topics, they contain a lot of general software development best practices. +* If this is your first contribution to CesiumJS, add your name to [CONTRIBUTORS.md](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/CONTRIBUTORS.md). * For an overview of our workflow see [github pull request workflows](http://cesiumjs.org/2013/10/08/GitHub-Pull-Request-Workflows/). * Pull request tips + * After you open a pull request, the friendly [cesium-concierge](https://github.com/AnalyticalGraphicsInc/cesium-concierge) bot will comment with a short automated review. At least one human will also review your pull request. * If your pull request fixes an existing issue, include a link to the issue in the description (like this: [#1](https://github.com/AnalyticalGraphicsInc/cesium/issues/1)). Likewise, if your pull request fixes an issue reported on the Cesium forum, include a link to the thread. * If your pull request needs additional work, include a [task list](https://github.com/blog/1375%0A-task-lists-in-gfm-issues-pulls-comments). * Once you are done making new commits to address feedback, add a comment to the pull request such as `"this is ready"` since GitHub doesn't notify us about commits. * Code and tests * Follow the [Coding Guide](Documentation/Contributors/CodingGuide/README.md). - * Verify your code passes [ESLint](http://www.eslint.org/). Run ESLint for all of Cesium with `npm run eslint` or automatically run ESLint when files are saved with `npm run eslint-watch`. See the [Build Guide](Documentation/Contributors/BuildGuide/README.md). + * Verify your code passes [ESLint](http://www.eslint.org/). Run ESLint for all of CesiumJS with `npm run eslint` or automatically run ESLint when files are saved with `npm run eslint-watch`. See the [Build Guide](Documentation/Contributors/BuildGuide/README.md). * Verify that all tests pass, and write new tests with excellent code coverage for new code. Follow the [Testing Guide](Documentation/Contributors/TestingGuide/README.md). - * If you added new identifiers to the Cesium API: + * If you added new identifiers to the CesiumJS API: * Update [CHANGES.md](CHANGES.md). * Include reference documentation with code examples. Follow the [Documentation Guide](Documentation/Contributors/DocumentationGuide/README.md). * If the change is significant, add a new [Sandcastle](http://cesiumjs.org/Cesium/Apps/Sandcastle/index.html) example or extend and existing one. diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index d6e882cf5d58..f7da17c53bc4 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -1,4 +1,4 @@ -See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to Cesium. The following people have contributed to Cesium, under the following agreements: +See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to CesiumJS. The following people have contributed to CesiumJS, under the following agreements: ## [Corporate CLA](Documentation/Contributors/CLAs/corporate-cla-agi-v1.0.txt) diff --git a/Documentation/Contributors/BuildGuide/README.md b/Documentation/Contributors/BuildGuide/README.md index bf35a4bc07b9..b0c438f34b9c 100644 --- a/Documentation/Contributors/BuildGuide/README.md +++ b/Documentation/Contributors/BuildGuide/README.md @@ -14,7 +14,7 @@ * Recommended Git settings: * `git config --global pull.rebase preserve` - when pulling remote changes, rebase your local changes on top of the remote changes, to avoid unnecessary merge commits. * `git config --global fetch.prune true` - when fetching remote changes, remove any remote branches that no longer exist on the remote. -* Have [commit access](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Documentation/Contributors/CommittersGuide/README.md) to cesium? +* Have [commit access](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Documentation/Contributors/CommittersGuide/README.md) to CesiumJS? * No * Fork [cesium](https://github.com/AnalyticalGraphicsInc/cesium). * Use the [GitHub website](https://github.com/AnalyticalGraphicsInc/cesium/branches/all) to delete all branches in your fork except `master`. @@ -118,7 +118,7 @@ Here's the full set of scripts and what they do. * `test-webgl-validation` - Runs all tests with Karma and enables low-level WebGL validation. * `test-release` - Runs all tests on the minified release version of built Cesium. * **Deployment scripts** - * `deploy-s3` - Deploys the built cesium files, the npm package, and the zip file to Amazon S3. This requires having credentials set up for the S3 bucket to which you are deploying. + * `deploy-s3` - Deploys the built CesiumJS files, the npm package, and the zip file to Amazon S3. This requires having credentials set up for the S3 bucket to which you are deploying. * `deploy-status` - Set the deployment statuses in GitHub, for use with Travis. * `deploy-set-version` - Sets the version of `package.json`, for use with Travis. @@ -130,7 +130,7 @@ Travis triggers a build whenever someone opens a pull request or pushes code to ![Checks](checks_failed.jpg) -You can also access the build of any branch of cesium by going to the [Cesium Branches](https://github.com/AnalyticalGraphicsInc/cesium/branches/all) page, and clicking the icon next to the branch name. +You can also access the build of any branch of CesiumJS by going to the [Cesium Branches](https://github.com/AnalyticalGraphicsInc/cesium/branches/all) page, and clicking the icon next to the branch name. ![Branches](branches.png) diff --git a/Documentation/Contributors/CodeReviewGuide/README.md b/Documentation/Contributors/CodeReviewGuide/README.md index c4ea6fde2dfb..b14e50b00074 100644 --- a/Documentation/Contributors/CodeReviewGuide/README.md +++ b/Documentation/Contributors/CodeReviewGuide/README.md @@ -1,10 +1,10 @@ -All code in Cesium is publicly peer reviewed. We review code to share knowledge, foster shared ownership, and improve code quality and consistency. +All code in CesiumJS is publicly peer reviewed. We review code to share knowledge, foster shared ownership, and improve code quality and consistency. This guide describes best practices for code reviewers. * [General](#general) * [Reviewing](#reviewing) -* [Changes to the Public Cesium API](#changes-to-the-public-cesium-api) +* [Changes to the Public CesiumJS API](#changes-to-the-public-cesium-api) * [Testing](#testing) * [Merging](#merging) * [Useful Git Commit Management](#useful-git-commit-management) @@ -22,7 +22,7 @@ This guide describes best practices for code reviewers. ## Reviewing * See the forest through the trees. Don't just review code one line at a time. Consider the big picture and its implications. -* _Comments are about code_, not the contributor who wrote the code. Don't be offended by a reviewer's comments and don't aim to offend when commenting. We all want the same thing: to improve Cesium. +* _Comments are about code_, not the contributor who wrote the code. Don't be offended by a reviewer's comments and don't aim to offend when commenting. We all want the same thing: to improve CesiumJS. * Provide motivation when it isn't obvious. Suggest why a change should be made. * Point contributors to a relevant part of the [Coding Guide](../CodingGuide/README.md) when useful. * _Be concise_. Make every word tell. @@ -31,9 +31,9 @@ This guide describes best practices for code reviewers. * Bring others into the conversation sparingly. If someone has expertise with a particular language feature or problem domain under review, invite them to comment with an `@mention`. * If an experienced contributor makes a occasional whitespace or trivial mistake, just fix it to save on noise and speedup the review. -## Changes to the Public Cesium API +## Changes to the Public CesiumJS API -* If new identifiers were added to the public Cesium API: +* If new identifiers were added to the public CesiumJS API: * Verify there is new reference doc. See the [Documentation Guide](../CodingGuide/README.md). * Verify that [CHANGES.md](../../../CHANGES.md) was updated. * Does the change warrant a new Sandcastle example? @@ -43,13 +43,13 @@ This guide describes best practices for code reviewers. ## Testing * Don't just review the code; test it by running the unit tests and relevant Sandcastle examples. See the [Testing Guide](../TestingGuide/README.md). -* For some changes, it is useful to profile Cesium or step through the code in the debugger. +* For some changes, it is useful to profile CesiumJS or step through the code in the debugger. * Read the new reference doc. Build the reference doc if the changes are significant. ## Merging * When a reviewer hits merge, the ideal is that they have enough knowledge of the new code that they could support it in the future. In practice, this isn't always realistic but we strive for it. -* Cesium uses Travis CI for continuous integration. Travis automatically builds Cesium, runs ESLint, and generates the documentation for each branch pushed to GitHub. Before merging a pull request, verify that all Travis checks pass, indicated by the green check-mark and green "Merge pull request" button: +* CesiumJS uses Travis CI for continuous integration. Travis automatically builds CesiumJS, runs ESLint, and generates the documentation for each branch pushed to GitHub. Before merging a pull request, verify that all Travis checks pass, indicated by the green check-mark and green "Merge pull request" button: ![Travis CI checks](Travis.jpg) diff --git a/Documentation/Contributors/CodingGuide/README.md b/Documentation/Contributors/CodingGuide/README.md index 1b30492e614b..2faefa3fe1cc 100644 --- a/Documentation/Contributors/CodingGuide/README.md +++ b/Documentation/Contributors/CodingGuide/README.md @@ -1,9 +1,11 @@ # Coding Guide -Cesium is one of the largest JavaScript codebases in the world. Since its start, we have maintained a high standard for code quality, which has made the codebase easier to work with for both new and experienced contributors. We hope you find the codebase to be clean and consistent. +CesiumJS is one of the largest JavaScript codebases in the world. Since its start, we have maintained a high standard for code quality, which has made the codebase easier to work with for both new and experienced contributors. We hope you find the codebase to be clean and consistent. In addition to describing typical coding conventions, this guide also covers best practices for design, maintainability, and performance. It is the cumulative advice of many developers after years of production development, research, and experimentation. +This guide applies to CesiumJS and all parts of the Cesium ecosystem written in JavaScript. + :art: The color palette icon indicates a design tip. :house: The house icon indicates a maintainability tip. The whole guide is, of course, about writing maintainable code. diff --git a/Documentation/Contributors/CommittersGuide/README.md b/Documentation/Contributors/CommittersGuide/README.md index 0627474d6ad9..acdbd054b2b9 100644 --- a/Documentation/Contributors/CommittersGuide/README.md +++ b/Documentation/Contributors/CommittersGuide/README.md @@ -13,4 +13,4 @@ * If a contributor has _significant and sustained_ contributions and should have commit access, propose it on cesium-committers@googlegroups.com. Following the [Apache Way](http://community.apache.org/newcommitter.html), they will be given commit access with three yes votes and no no's over a week. To keep with the community spirit of the project, this is independent of affiliation; no one is entitled to commit access solely based on their affiliation. See Producing Open Source Software: [Money Can't Buy You Love](http://producingoss.com/en/money-vs-love.html) and [Committers](http://producingoss.com/en/committers.html). * If a committer is inactive for one year, they lose commit access. -* Everyone with commit access to the main Cesium repo must enable [two-factor authentication](https://help.github.com/articles/about-two-factor-authentication) on their GitHub account. +* Everyone with commit access to the main CesiumJS repo must enable [two-factor authentication](https://help.github.com/articles/about-two-factor-authentication) on their GitHub account. diff --git a/Documentation/Contributors/DocumentationGuide/README.md b/Documentation/Contributors/DocumentationGuide/README.md index 4fa4e4b854c7..3f4cda3e95f8 100644 --- a/Documentation/Contributors/DocumentationGuide/README.md +++ b/Documentation/Contributors/DocumentationGuide/README.md @@ -1,10 +1,10 @@ # Documentation Guide -Cesium's reference documentation is one of the most popular sections of the Cesium website, and a critical resource for developers. +CesiumJS's reference documentation is one of the most popular sections of the CesiumJS website, and a critical resource for developers. This guide describes best practices for writing reference doc. -Always include doc for new identifiers (classes, functions, properties, constants) in the public Cesium API. +Always include doc for new identifiers (classes, functions, properties, constants) in the public CesiumJS API. Generally, just follow the patterns that are already in comparable parts of the code, e.g., if you are documenting a new utility function in `Core`, look at a function in `Core` such as [`binarySearch`](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Source/Core/binarySearch.js); likewise, if you are documenting a new class in `Scene`, look at a similar class such as [`Model`](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Source/Scene/Model.js). @@ -28,13 +28,13 @@ Generally, just follow the patterns that are already in comparable parts of the ## Building the Doc -The reference doc is written in JavaScript code comments using [JSDoc3](http://usejsdoc.org/index.html) tags. At the command line, build the doc from the root Cesium directory by running the following: +The reference doc is written in JavaScript code comments using [JSDoc3](http://usejsdoc.org/index.html) tags. At the command line, build the doc from the root CesiumJS directory by running the following: ``` npm run generateDocumentation ``` This creates a `Build/Documentation` directory with the built HTML files. -There is a link to the doc from Cesium's main `index.html` when running +There is a link to the doc from CesiumJS's main `index.html` when running ``` npm start ``` @@ -43,7 +43,7 @@ npm start ## Basics -Consider one of the simplest functions in Cesium, `defined`: +Consider one of the simplest functions in CesiumJS, `defined`: ```javascript /** * @exports defined @@ -108,7 +108,7 @@ Matrix4.fromRotationTranslation = function(rotation, translation, result) { generates ![](fromRotationTranslation.jpg) -The Cesium classes in the `Type` column are links to their doc. +The CesiumJS classes in the `Type` column are links to their doc. ## `options` Parameters diff --git a/Documentation/Contributors/README.md b/Documentation/Contributors/README.md index fd923758d4f1..d17c7e3838cf 100644 --- a/Documentation/Contributors/README.md +++ b/Documentation/Contributors/README.md @@ -1,13 +1,13 @@ # Contributor Guides * [CONTRIBUTING.md](../../CONTRIBUTING.md) - Start here. How to find something to work on, submit issues, and open pull requests. -* [Build Guide](BuildGuide/README.md) - How to build and run Cesium locally. -* **IDEs** - use any IDE you want for Cesium development. Most contributors use WebStorm (commercial) or VSCode (open source). +* [Build Guide](BuildGuide/README.md) - How to build and run CesiumJS locally. +* **IDEs** - use any IDE you want for CesiumJS development. Most contributors use WebStorm (commercial) or VSCode (open source). * [WebStorm Guide](WebStormGuide/README.md) - How to set up WebStorm. * [VSCode Guide](VSCodeGuide/README.md) - How to set up VSCode. * [Coding Guide](CodingGuide/README.md) - JavaScript and GLSL coding conventions and best practices for design, maintainability, and performance. -* [Testing Guide](TestingGuide/README.md) - How to run the Cesium tests and write awesome tests. +* [Testing Guide](TestingGuide/README.md) - How to run the CesiumJS tests and write awesome tests. * [Documentation Guide](DocumentationGuide/README.md) - How to write great reference documentation. * [Code Review Guide](CodeReviewGuide/README.md) - Best practices for reviewing code in pull requests. * [Presenter's Guide](PresentersGuide/README.md) - Tips for giving talks. -* [Committer's Guide](CommittersGuide/README.md) - What to do with commit access to the main Cesium repo. +* [Committer's Guide](CommittersGuide/README.md) - What to do with commit access to the main CesiumJS repo. diff --git a/Documentation/Contributors/TestingGuide/README.md b/Documentation/Contributors/TestingGuide/README.md index eb8bd8cf9547..64f38a73149d 100644 --- a/Documentation/Contributors/TestingGuide/README.md +++ b/Documentation/Contributors/TestingGuide/README.md @@ -1,8 +1,8 @@ # Testing Guide -Our development culture is committed to testing. Cesium is used in diverse use cases on a wide array of platforms so it is important for it to be well tested. +Our development culture is committed to testing. CesiumJS is used in diverse use cases on a wide array of platforms so it is important for it to be well tested. -As of Cesium 1.35, Cesium has over 8,800 tests with 93% code coverage. Cesium has as much test code (126K lines) as engine code (126K). We are unaware of any other project of this size and lifetime and with this many contributors that has similar stats. +As of CesiumJS 1.35, CesiumJS has over 8,800 tests with 93% code coverage. CesiumJS has as much test code (126K lines) as engine code (126K). We are unaware of any other project of this size and lifetime and with this many contributors that has similar stats. All new code should have 100% code coverage and should pass all tests. Always run the tests before opening a pull request. @@ -16,7 +16,7 @@ All new code should have 100% code coverage and should pass all tests. Always r * [Run All Tests against Combined File (Run All Tests against Combined File with Debug Code Removed)]() * [Run All Tests with Code Coverage (Build 'instrumentForCoverage' First)](#run-all-tests-against-combined-file-run-all-tests-against-combined-file-with-debug-code-removed) * [Running Tests on the Command Line with Karma](#running-tests-on-the-command-line-with-karma) -* [Testing Previous Versions of Cesium](#testing-previous-versions-of-cesium) +* [Testing Previous Versions of CesiumJS](#testing-previous-versions-of-cesium) * [`testfailure` Label for Issues](#testfailure-label-for-issues) * [Writing Tests](#writing-tests) * [Directory Organization](#directory-organization) @@ -42,13 +42,13 @@ All new code should have 100% code coverage and should pass all tests. Always r ## Running the Tests -The Cesium tests are written in JavaScript and use [Jasmine](http://jasmine.github.io/), a behavior-driven testing framework. Jasmine calls an individual test, e.g., a function with one or more assertions, a **spec** (however, the Cesium team usually still say "test"), and a group of related tests, e.g., all the tests for `Cartesian3`, a **suite**. Jasmine also calls an assertion, an **expectation**. +The CesiumJS tests are written in JavaScript and use [Jasmine](http://jasmine.github.io/), a behavior-driven testing framework. Jasmine calls an individual test, e.g., a function with one or more assertions, a **spec** (however, the Cesium team usually still say "test"), and a group of related tests, e.g., all the tests for `Cartesian3`, a **suite**. Jasmine also calls an assertion, an **expectation**. -When running Cesium locally, browse to [http://localhost:8080/](http://localhost:8080/) and there are several test options: +When running CesiumJS locally, browse to [http://localhost:8080/](http://localhost:8080/) and there are several test options: ### Run All Tests -Runs all the tests. As of Cesium 1.15, on a decent laptop, they run in about a minute in Chrome. It is important that the tests run quickly so we run them often. +Runs all the tests. As of CesiumJS 1.15, on a decent laptop, they run in about a minute in Chrome. It is important that the tests run quickly so we run them often. When all the tests pass, the page looks like this: @@ -66,11 +66,11 @@ Click on the failed test to rerun just that test. This is useful for saving tim #### Run with WebGL validation -The link to **Run with WebGL validation** passes a query parameter to the tests to enable extra low-level WebGL validation such as calling `gl.getError()` after each WebGL call. We use this when doing the monthly Cesium release and when making changes to Cesium's renderer. +The link to **Run with WebGL validation** passes a query parameter to the tests to enable extra low-level WebGL validation such as calling `gl.getError()` after each WebGL call. We use this when doing the monthly CesiumJS release and when making changes to CesiumJS's renderer. #### Run with WebGL stub -The **Run with WebGL stub** link passes a query parameter to the tests to use Cesium's WebGL stub. This makes all WebGL calls a noop and ignores test expectations that rely on reading back from WebGL. This allows running the tests on CI where a reasonable WebGL implementation is not available and still getting full code coverage albeit not all verification. +The **Run with WebGL stub** link passes a query parameter to the tests to use CesiumJS's WebGL stub. This makes all WebGL calls a noop and ignores test expectations that rely on reading back from WebGL. This allows running the tests on CI where a reasonable WebGL implementation is not available and still getting full code coverage albeit not all verification. ### Select a Test to Run @@ -94,25 +94,25 @@ Suites can have a category associated with them. This option runs all tests in Likewise, this option runs all tests not in the WebGL category. -Perhaps surprisingly, this is the bulk of Cesium tests, which include math and geometry tests, imagery provider tests, data source tests, etc. +Perhaps surprisingly, this is the bulk of CesiumJS tests, which include math and geometry tests, imagery provider tests, data source tests, etc. These tests run quickly (for example, 15 seconds compared to 60) and are very reliable across systems since they do not rely on the underlying WebGL implementation, which can vary based on the browser, OS, driver, and GPU. ### Run All Tests against Combined File (Run All Tests against Combined File with Debug Code Removed) -Most test options load Cesium using the individual source files in the `Source` directory, which is great for debugging. +Most test options load CesiumJS using the individual source files in the `Source` directory, which is great for debugging. -However, many users build apps using the built Cesium.js in `Build/Cesium` (which is created, for example, by running `npm run combine`). This option runs the tests using this instead of individual Cesium source files. +However, many users build apps using the built Cesium.js in `Build/Cesium` (which is created, for example, by running `npm run combine`). This option runs the tests using this instead of individual CesiumJS source files. The **Run All Tests against Combined File with Debug Code Removed** is the same except it is for use with the release version of the built Cesium.js (which is created, for example, by running `npm run combineRelease`). The release version has `DeveloperError` exceptions optimized out so this test option makes `toThrowDeveloperError` always pass. -See the [Contributor's Guide](https://github.com/AnalyticalGraphicsInc/cesium/wiki/Contributor%27s-Guide) for all the Cesium build options. +See the [Contributor's Guide](https://github.com/AnalyticalGraphicsInc/cesium/wiki/Contributor%27s-Guide) for all the CesiumJS build options. ### Run All Tests with Code Coverage (Build 'instrumentForCoverage' First) [JSCoverage](http://siliconforks.com/jscoverage/) is used for code coverage. It is especially important to have outstanding code coverage since JavaScript doesn't have a compiler and linker to catch early errors. -To run code coverage, first create a build of Cesium that is instrumented for coverage by running `npm run instrumentForCoverage`. Currently, this is Windows only. +To run code coverage, first create a build of CesiumJS that is instrumented for coverage by running `npm run instrumentForCoverage`. Currently, this is Windows only. Then use this test option to run the tests with code coverage. Click on the `Summary` tab to see the total code coverage and coverage for each individual source file. @@ -125,7 +125,7 @@ Click on a file to see line-by-line coverage for just that file. For example, h In the left margin, green indicates a line that was executed, and red indicates a line that was not. Many lines, such as comments and semicolons, are not colored since they are not executable. For the `contains` function above - * `AssociativeArray.prototype.contains = function(key) {` is executed once when Cesium is loaded to assign the `contains` function to the `AssociativeArray`'s prototype. + * `AssociativeArray.prototype.contains = function(key) {` is executed once when CesiumJS is loaded to assign the `contains` function to the `AssociativeArray`'s prototype. * The `if` statement and return statement are executed 3,425 times. * The `throw` statement is not executed, which indicates that test coverage should be improved here. We strive to test _all_ error conditions. @@ -186,7 +186,7 @@ It is also possible for Karma to run all tests against each browser installed on `npm run test-non-webgl` -#### Run All Tests Against the Minified Release Version of Cesium +#### Run All Tests Against the Minified Release Version of CesiumJS `npm run test-release` @@ -194,19 +194,19 @@ It is also possible for Karma to run all tests against each browser installed on Sometimes it is useful to run a single test or suite for easier debugging purposes. To do this simply change the `it` function call for the desired test to `fit`, the `f` stands for `focused` in Jasmine speak. Likewise, to run an entire suite, use `fdefineSuite` instead of `defineSuite`. -## Testing Previous Versions of Cesium +## Testing Previous Versions of CesiumJS -Sometimes it is useful to see if an issue exists in a previous version of Cesium. The tests for all versions of Cesium back to b15 (April 2013) are hosted on the Cesium website via the [downloads page](http://cesiumjs.org/downloads.html). Use the "Documentation, Sandcastle, tests, etc." links. +Sometimes it is useful to see if an issue exists in a previous version of CesiumJS. The tests for all versions of CesiumJS back to b15 (April 2013) are hosted on the CesiumJS website via the [downloads page](http://cesiumjs.org/downloads.html). Use the "Documentation, Sandcastle, tests, etc." links. ## `testfailure` Label for Issues -Despite our best efforts, sometimes tests fail. This is often due to a new browser, OS, or driver bug that breaks a test that previously passed. If this indicates a bug in Cesium, we strive to quickly fix it. Likewise, if it indicates that Cesium needs to work around the issue (for example, as we [did for Safari 9](https://github.com/AnalyticalGraphicsInc/cesium/issues/2989)), we also strive to quickly fix it. +Despite our best efforts, sometimes tests fail. This is often due to a new browser, OS, or driver bug that breaks a test that previously passed. If this indicates a bug in CesiumJS, we strive to quickly fix it. Likewise, if it indicates that CesiumJS needs to work around the issue (for example, as we [did for Safari 9](https://github.com/AnalyticalGraphicsInc/cesium/issues/2989)), we also strive to quickly fix it. -If a test failure is likely due to a browser, OS, or driver bug, or a poorly written test, and the failure does not impact actual Cesium apps, we sometimes submit an issue with the [testfailure](https://github.com/AnalyticalGraphicsInc/cesium/labels/test%20failure) label to fix it at a later time. A great way to contribute to Cesium is to help fix these issues. +If a test failure is likely due to a browser, OS, or driver bug, or a poorly written test, and the failure does not impact actual CesiumJS apps, we sometimes submit an issue with the [testfailure](https://github.com/AnalyticalGraphicsInc/cesium/labels/test%20failure) label to fix it at a later time. A great way to contribute to CesiumJS is to help fix these issues. ## Writing Tests -We _love_ to write tests. We often write them as we write engine code (meaning Cesium itself). Or if the engine code is experimental, we make a second pass and write tests before opening a pull request. Sometimes we do both: we write tests right away for the new code we expect to be stable, and we wait to write tests for the code in flux. +We _love_ to write tests. We often write them as we write engine code (meaning CesiumJS itself). Or if the engine code is experimental, we make a second pass and write tests before opening a pull request. Sometimes we do both: we write tests right away for the new code we expect to be stable, and we wait to write tests for the code in flux. ### Directory Organization @@ -214,17 +214,17 @@ Tests are located in the [Specs](https://github.com/AnalyticalGraphicsInc/cesium ### Bottom-Up Unit Testing -The Cesium tests are largely **unit tests** because they test individual units, e.g., functions or classes. The simplest units are tested individually, and then units built upon other units are also tested. This allows us to build Cesium on well-tested foundations and to quickly narrow down issues. +The CesiumJS tests are largely **unit tests** because they test individual units, e.g., functions or classes. The simplest units are tested individually, and then units built upon other units are also tested. This allows us to build CesiumJS on well-tested foundations and to quickly narrow down issues. For example, a [`BoundingSphere`](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Source/Core/BoundingSphere.js) is composed of a `Cartesian3` that defines its center and a number that defines its radius. Even though tests for `BoundingSphere` implicitly test parts of `Cartesian3`, there are separate tests that explicitly test `Cartesian3` as a unit so anything that relies on `Cartesian3` knows it is already tested. -Often, we also test private units individually for the same reason. For example, [`ShaderCache`](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Source/Renderer/ShaderCache.js) is a private class in Cesium used by primitives, but it is still individually tested in [ShaderCacheSpec.js](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Specs/Renderer/ShaderCacheSpec.js). +Often, we also test private units individually for the same reason. For example, [`ShaderCache`](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Source/Renderer/ShaderCache.js) is a private class in CesiumJS used by primitives, but it is still individually tested in [ShaderCacheSpec.js](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Specs/Renderer/ShaderCacheSpec.js). Sometimes classes or functions are even designed with a separation specifically to enable more precise testing. For example, see [`getStringFromTypedArray`](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Source/Core/getStringFromTypedArray.js) and [getStringFromTypedArraySpec.js](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Specs/Core/getStringFromTypedArraySpec.js). ### Test Code is Code -Tests are written in JavaScript using Jasmine. It is important to realize that the tests themselves are code, just like Cesium. As such, the test code is held to the same standards as the engine code: it should be well organized, cohesive, loosely coupled, fast, and go through peer review. +Tests are written in JavaScript using Jasmine. It is important to realize that the tests themselves are code, just like CesiumJS. As such, the test code is held to the same standards as the engine code: it should be well organized, cohesive, loosely coupled, fast, and go through peer review. ### Testing Basics @@ -256,7 +256,7 @@ This test constructs a default `Cartesian3` object and then expects that the `x` Tests should have at least one `expect` call, but they may also have several as long as the test is cohesive. A test should test one behavior; if a test grows too complicated, it is hard to debug when it fails. To test one function may only require one test with one `expect`, or it may require multiple tests, each with multiple `expect` statements. It depends on context. Experience, peer review, and the existing tests will help guide you. -The above test does not require creating a `Viewer` widget or even a WebGL context; the only part of Cesium it uses is `Cartesian3` and anything it depends on. +The above test does not require creating a `Viewer` widget or even a WebGL context; the only part of CesiumJS it uses is `Cartesian3` and anything it depends on. > To learn the ins and outs of Jasmine, take 15 minutes to go through their [examples](http://jasmine.github.io/2.2/introduction.html). We will not cover all the details in this guide. @@ -273,7 +273,7 @@ it('angleBetween works for acute angles', function() { }); ``` -`toEqualEpsilon` is a custom Jasmine matcher that the Cesium tests add. See [Specs/addDefaultMatchers.js](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Specs/addDefaultMatchers.js) for all the custom matchers. In general, all test utility functions are in files in the `Specs` root directory. +`toEqualEpsilon` is a custom Jasmine matcher that the CesiumJS tests add. See [Specs/addDefaultMatchers.js](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Specs/addDefaultMatchers.js) for all the custom matchers. In general, all test utility functions are in files in the `Specs` root directory. For more on comparing floating-point numbers, see [Comparing Floating Point Numbers, 2012 Edition](https://randomascii.wordpress.com/2012/02/25/comparing-floating-point-numbers-2012-edition/). @@ -334,19 +334,19 @@ it('renders', function() { The test knows `scene` will be defined and does not need to worry about cleaning up the `scene` because `afterEach` and `afterAll` take care of it. -We strive to write isolated isolated tests so that a test can be run individually and produce the same results as when running the suite containing the test or all Cesium tests. Therefore, a test should not depend, for example, on a previous test setting global state. +We strive to write isolated isolated tests so that a test can be run individually and produce the same results as when running the suite containing the test or all CesiumJS tests. Therefore, a test should not depend, for example, on a previous test setting global state. The tests in the `'WebGL'` category do not strictly follow this pattern. Creating a WebGL context (which is implicit, for example, in `createScene`) is slow. Because it creates a lot of contexts, e.g., one per test, it is not well supported in browsers. So the tests use the pattern in the code example below where a `scene` (or `viewer` or `context`) has the lifetime of the suite using `beforeAll` and `afterAll`. ### Rendering Tests -Unlike the `Cartesian3` tests we first saw, many tests need to construct the main Cesium `Viewer` widget or one of its major components. Low-level renderer tests construct just `Context` (which, itself, has a canvas and WebGL context), and primitive tests construct a `Scene` (which contains a `Context`). +Unlike the `Cartesian3` tests we first saw, many tests need to construct the main CesiumJS `Viewer` widget or one of its major components. Low-level renderer tests construct just `Context` (which, itself, has a canvas and WebGL context), and primitive tests construct a `Scene` (which contains a `Context`). -As shown above, these tests use Cesium test utility functions: `createViewer`, `createScene`, or `createContext`. These functions honor query parameters passed to the tests (e.g., enabling WebGL validation or the WebGL stub) and add a few utility functions to the returned object. For example, `createScene` creates a 1x1 pixel canvas with a Cesium Scene and adds `renderForSpecs` (to initialize and render a frame) and `destroyForSpecs` to the returned `Scene` object. +As shown above, these tests use CesiumJS test utility functions: `createViewer`, `createScene`, or `createContext`. These functions honor query parameters passed to the tests (e.g., enabling WebGL validation or the WebGL stub) and add a few utility functions to the returned object. For example, `createScene` creates a 1x1 pixel canvas with a CesiumJS Scene and adds `renderForSpecs` (to initialize and render a frame) and `destroyForSpecs` to the returned `Scene` object. -> Most Cesium apps do not render the scene directly; instead, the `Viewer` object's default render loop renders the scene implicit to the user. The tests are an exception; most tests explicitly render the scene. +> Most CesiumJS apps do not render the scene directly; instead, the `Viewer` object's default render loop renders the scene implicit to the user. The tests are an exception; most tests explicitly render the scene. -Cesium adds several custom Jasmine matchers to make the rendering tests more concise and to support running tests with the WebGL stub. When using the WebGL stub, the WebGL implementation is a noop, and test expectations that rely on reading back from WebGL are ignored. The rendering custom matchers are: +CesiumJS adds several custom Jasmine matchers to make the rendering tests more concise and to support running tests with the WebGL stub. When using the WebGL stub, the WebGL implementation is a noop, and test expectations that rely on reading back from WebGL are ignored. The rendering custom matchers are: * `toRender` * `notToRender` @@ -380,7 +380,7 @@ Like most rendering tests, the first example uses a coarse-grained expectation t The second test verifies that the pixel value is the same as the default background color since the primitive's `show` property is `false`. -`toRender` and `notToRender` can also render the scene at a given Cesium simulation time, e.g.,: +`toRender` and `notToRender` can also render the scene at a given CesiumJS simulation time, e.g.,: ```javascript expect({ @@ -430,7 +430,7 @@ expect({ }).toReadPixels([0, 0, 0, 255]); ``` -Low-level Cesium renderer tests use just a `Context` without a Cesium `Scene`, and use the `contextToRender` and `notContextToRender` custom matchers to render a WebGL point primitive to the context's 1x1 viewport and verify the RGBA value, e.g.: +Low-level CesiumJS renderer tests use just a `Context` without a CesiumJS `Scene`, and use the `contextToRender` and `notContextToRender` custom matchers to render a WebGL point primitive to the context's 1x1 viewport and verify the RGBA value, e.g.: ```javascript expect({ @@ -458,7 +458,7 @@ it('can declare automatic uniforms', function() { ### GLSL -GLSL is the shading language used by WebGL to run small graphics programs in parallel on the GPU. Under-the-hood, Cesium contains a library of GLSL identifiers and functions. These are unit tested by writing a simple fragment shader that outputs white if the test passes. For example, here is an excerpt from [BuiltinFunctionsSpec.js](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Specs/Renderer/BuiltinFunctionsSpec.js); +GLSL is the shading language used by WebGL to run small graphics programs in parallel on the GPU. Under-the-hood, CesiumJS contains a library of GLSL identifiers and functions. These are unit tested by writing a simple fragment shader that outputs white if the test passes. For example, here is an excerpt from [BuiltinFunctionsSpec.js](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Specs/Renderer/BuiltinFunctionsSpec.js); ```javascript var context; @@ -574,7 +574,7 @@ Make external requests that assume the tests are being used with an Internet con (For an introduction to promises, see [JavaScript Promises - There and back again](http://www.html5rocks.com/en/tutorials/es6/promises/)). -For asynchronous testing, Jasmine's `it` function uses a `done` callback. For better integration with Cesium's asynchronous patterns, Cesium replaces `it` with a function that can return promises. +For asynchronous testing, Jasmine's `it` function uses a `done` callback. For better integration with CesiumJS's asynchronous patterns, CesiumJS replaces `it` with a function that can return promises. Here is an excerpt from [ModelSpec.js](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Specs/Scene/ModelSpec.js): @@ -615,7 +615,7 @@ function loadModelJson(gltf) { } ``` -Since loading a model requires asynchronous requests and creating WebGL resources that may be spread over several frames, Cesium's `pollToPromise` is used to return a promise that resolves when the model is ready, which occurs by rendering the scene in an implicit loop (hence the name "poll") until `model.ready` is `true` or the `timeout` is reached. +Since loading a model requires asynchronous requests and creating WebGL resources that may be spread over several frames, CesiumJS's `pollToPromise` is used to return a promise that resolves when the model is ready, which occurs by rendering the scene in an implicit loop (hence the name "poll") until `model.ready` is `true` or the `timeout` is reached. `pollToPromise` is used in many places where a test needs to wait for an asynchronous event before testing its expectations. Here is an excerpt from [BillboardCollectionSpec.js](https://github.com/AnalyticalGraphicsInc/cesium/blob/master/Specs/Scene/BillboardCollectionSpec.js): @@ -718,11 +718,11 @@ defineSuite([ }, 'WebGL'); ``` -`defineSuite` is a custom Cesium function that wraps Jasmine define calls and provides the category capability. +`defineSuite` is a custom CesiumJS function that wraps Jasmine define calls and provides the category capability. ## Manual Testing -Sometimes running the unit tests is all that is needed to verify new code. However, we often also manually run Cesium to see the effects of new code. Sometimes it is as simple as running Cesium Viewer before opening a pull request, perhaps because we just added a new function to `Cartesian3`. Other times, it is as involved as going through each example in Sandcastle and testing the different options because, for example, we refactored the renderer for WebGL 2. Most often, there is a middle ground, for example, we added a new feature to `Model` so we ran the Sandcastle examples that create 3D Models. +Sometimes running the unit tests is all that is needed to verify new code. However, we often also manually run CesiumJS to see the effects of new code. Sometimes it is as simple as running CesiumJS Viewer before opening a pull request, perhaps because we just added a new function to `Cartesian3`. Other times, it is as involved as going through each example in Sandcastle and testing the different options because, for example, we refactored the renderer for WebGL 2. Most often, there is a middle ground, for example, we added a new feature to `Model` so we ran the Sandcastle examples that create 3D Models. ## Pragmatic Advice @@ -730,11 +730,11 @@ Advice from [@pjcozzi](https://github.com/pjcozzi): ### Start with a Similar (Small) Test -> Since I wrote the very first Cesium test, I have not written a suite - or even individual test - from scratch. I suspect no one does. +> Since I wrote the very first CesiumJS test, I have not written a suite - or even individual test - from scratch. I suspect no one does. ![](6.jpg) -The first 73 Cesium tests from March 2011. +The first 73 CesiumJS tests from March 2011. > Instead, start with a similar suite or test, copy it, strip it down to the minimum you need, and then start adding your specific code. For example, if you are adding a new math type, start with Cartesian3Spec.js or Matrix4Spec.js. If you are adding a new primitive, start with DebugModelMatrixPrimitiveSpec.js. @@ -748,7 +748,7 @@ The first 73 Cesium tests from March 2011. ## Testing in WebStorm -When you load the Cesium WebStorm project, there will already be a predefined run configuration for executing the unit tests. It will be in the upper-right corner and look something like the below: +When you load the CesiumJS WebStorm project, there will already be a predefined run configuration for executing the unit tests. It will be in the upper-right corner and look something like the below: ![](webstorm-test-configuration.png) @@ -764,4 +764,4 @@ To make jumping between the source and spec files easier download the [Cesium W ## Resources -See Section 4.4 of [Getting Serious with JavaScript](http://webglinsights.github.io/downloads/WebGL-Insights-Chapter-4.pdf) by Cesium contributors Matthew Amato and Kevin Ring in _WebGL Insights_ for a deeper but less broad presentation of Cesium testing. +See Section 4.4 of [Getting Serious with JavaScript](http://webglinsights.github.io/downloads/WebGL-Insights-Chapter-4.pdf) by CesiumJS contributors Matthew Amato and Kevin Ring in _WebGL Insights_ for a deeper but less broad presentation of CesiumJS testing. diff --git a/Documentation/Contributors/VSCodeGuide/README.md b/Documentation/Contributors/VSCodeGuide/README.md index 03d38e30c4f5..1d7dc658705b 100644 --- a/Documentation/Contributors/VSCodeGuide/README.md +++ b/Documentation/Contributors/VSCodeGuide/README.md @@ -6,9 +6,9 @@ `npm install -g gulp-cli` from a bash prompt. This does not require administrative rights, and places a `gulp` shim into your path that will invoke a copy of gulp from the local project folder. This is needed for -VSCode's build tasks to work with Cesium. +VSCode's build tasks to work with CesiumJS. -3. Click `File -> Open Folder...` and open the Cesium root folder. +3. Click `File -> Open Folder...` and open the CesiumJS root folder. ## Shell Integration (optional) @@ -36,19 +36,19 @@ higher installed, to get the correct integrated shell behavior. Click on the extensions icon, or press CTRL-SHIFT-X to see the list of installed VSCode extensions. While we don't officially endorse any particular 3rd-party -extension, there are some that appear to be quite useful to Cesium. Just enter +extension, there are some that appear to be quite useful to CesiumJS. Just enter the desired extension name in the search box and click install. You will need to restart VSCode after you are done installing extensions. * **[eslint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)** -by Dirk Baeumer -- This extension picks up on Cesium's own eslint settings, -and will warn of any violations. The Cesium main repository should pass eslint -using the Cesium eslint settings with no warnings and no errors. Proposed -contributions to Cesium that introduce eslint warnings will need to be corrected +by Dirk Baeumer -- This extension picks up on CesiumJS's own eslint settings, +and will warn of any violations. The CesiumJS main repository should pass eslint +using the CesiumJS eslint settings with no warnings and no errors. Proposed +contributions to CesiumJS that introduce eslint warnings will need to be corrected before they are accepted. * **[Shader languages support for VS Code](https://marketplace.visualstudio.com/items?itemName=slevesque.shader)** -by slevesque -- This extension provides syntax highlighting for Cesium's shader code. +by slevesque -- This extension provides syntax highlighting for CesiumJS's shader code. * **[Prettify JSON](https://marketplace.visualstudio.com/items?itemName=mohsen1.prettify-json)** by Mohsen Azimi -- This seems generally useful. @@ -58,7 +58,7 @@ by CesiumJS.org -- This extension adds features for previewing and editing 3D mo ## VSCode Tasks and Files -You can launch any of Cesium's npm tasks from within VSCode by pressing +You can launch any of CesiumJS's npm tasks from within VSCode by pressing CTRL-P and typing `task ` (with a trailing space). Autocomplete will offer the list of npm tasks for you to run. The first time you do this, allow a moment for it to read the available tasks from the gulpfile. @@ -66,15 +66,15 @@ allow a moment for it to read the available tasks from the gulpfile. You can also jump to any source file with the same CTRL-P keypress followed by the name of the file. -## Building Cesium +## Building CesiumJS -Cesium has a number of GLSL shaders and auto-generated files that must be -built before Cesium can be used. The simplest way in VSCode is to type +CesiumJS has a number of GLSL shaders and auto-generated files that must be +built before CesiumJS can be used. The simplest way in VSCode is to type `CTRL-P` `task build` to trigger a single build. You can also start the build watcher with `CTRL-P` `task build-watch`. This leaves a watcher running until you exit VSCode, that will automatically -update any shaders or auto-generated files to reflect changes to Cesium as +update any shaders or auto-generated files to reflect changes to CesiumJS as you save them. Keep in mind that `build-watch` will quietly terminate when diff --git a/Documentation/Contributors/WebStormGuide/README.md b/Documentation/Contributors/WebStormGuide/README.md index 8bd4e93efe12..ebcb2d0acd3d 100644 --- a/Documentation/Contributors/WebStormGuide/README.md +++ b/Documentation/Contributors/WebStormGuide/README.md @@ -4,11 +4,11 @@ Install [WebStorm](https://www.jetbrains.com/webstorm/). While it's a commercial IDE, it's pretty cheap and there's a 30-day free trial. -WebStorm requires very little configuration out of the box. Just browse to and open the WebStorm project included with Cesium. Most things a Web Developer would want are built-in. Whenever you open a file that has a plugin available, such as `md`, `glsl`, or `.gitignore`, WebStorm will ask if you want to install it. Simply say yes and off you go. While most of us still use `git` on the command-line, WebStorm includes excellent tools for merging, diffing, and managing branches as well. +WebStorm requires very little configuration out of the box. Just browse to and open the WebStorm project included with CesiumJS. Most things a Web Developer would want are built-in. Whenever you open a file that has a plugin available, such as `md`, `glsl`, or `.gitignore`, WebStorm will ask if you want to install it. Simply say yes and off you go. While most of us still use `git` on the command-line, WebStorm includes excellent tools for merging, diffing, and managing branches as well. ### Gulp Integration -Cesium's build scripts use gulp. WebStorm has excellent gulp integration for running tasks from the IDE. Just right-click on `gulpfile.js` in the Project tree and select `Show Gulp Tasks`, now you can double click on any task to run it. Even better, perpetual tasks like `build-watch` and `jsHint-watch` +CesiumJS's build scripts use gulp. WebStorm has excellent gulp integration for running tasks from the IDE. Just right-click on `gulpfile.js` in the Project tree and select `Show Gulp Tasks`, now you can double click on any task to run it. Even better, perpetual tasks like `build-watch` and `jsHint-watch` will get their own output tab that automatically updates. ### WebStorm Plugins diff --git a/LICENSE.md b/LICENSE.md index 2b5dfeaac303..7251c3dfd407 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,4 +1,4 @@ -Copyright 2011-2017 Cesium Contributors +Copyright 2011-2018 CesiumJS Contributors Apache License Version 2.0, January 2004 @@ -188,7 +188,7 @@ Copyright 2011-2017 Cesium Contributors same "printed page" as the copyright notice for easier identification within third-party archives. - Copyright 2011-2017 Cesium Contributors + Copyright 2011-2018 CesiumJS Contributors Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -207,7 +207,7 @@ Patents 9153063 and 9865085 Third-Party Code ================ -Cesium includes the following third-party code. +CesiumJS includes the following third-party code. ### Sean O'Neil @@ -673,7 +673,7 @@ https://github.com/KhronosGroup/glTF-WebGL-PBR Tests ===== -The Cesium tests use the following third-party libraries and data. +The CesiumJS tests use the following third-party libraries and data. ### Jasmine @@ -688,10 +688,10 @@ Copyright (c) 2008-2014 Pivotal Labs > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -Cesium Documentation +CesiumJS Documentation ==================== -The Cesium documentation files include the following third-party content. +The CesiumJS documentation files include the following third-party content. ### Source Sans Pro (Font) @@ -703,7 +703,7 @@ Source® Sans Pro, Adobe's first open source typeface family, was designed by Pa Example Applications ==================== -The Cesium example applications include the following third-party libraries and data. +The CesiumJS example applications include the following third-party libraries and data. ### Dojo Toolkit diff --git a/README.md b/README.md index ce1a30e57d48..4e136d1f081d 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ npm install cesium Have questions? Ask them on the [forum](http://cesiumjs.org/forum.html). -Interested in contributing? See [CONTRIBUTING.md](CONTRIBUTING.md). +Interested in contributing? See [CONTRIBUTING.md](CONTRIBUTING.md). :heart: ### :snowflake: Mission ### @@ -31,8 +31,8 @@ Our mission is to create the leading 3D globe and map for static and time-dynami ### :earth_americas: Where Does the 3D Content Come From? ### CesiumJS can stream 3D content such as terrain, imagery, and 3D Tiles from the commercial [Cesium ion](https://cesium.com/blog/2018/03/01/hello-cesium-ion/) -platform and other content sources. You are free to use any combination of content sources with CesiumJS you please, -but using Cesium ion helps support CesiumJS development. :heart: +platform and other content sources. You are free to use any combination of content sources with CesiumJS that you please. +Using Cesium ion helps support CesiumJS development. :heart: ### :clap: Featured Demos ### diff --git a/package.json b/package.json index 4889d44cdbb0..825d2cfb188f 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "cesium", "version": "1.42.1", - "description": "Cesium is a JavaScript library for creating 3D globes and 2D maps in a web browser without a plugin.", + "description": "CesiumJS is a JavaScript library for creating 3D globes and 2D maps in a web browser without a plugin.", "homepage": "http://cesiumjs.org", "license": "Apache-2.0", "author": { @@ -10,7 +10,7 @@ }, "contributors": [ { - "name": "Cesium community", + "name": "CesiumJS community", "url": "https://github.com/AnalyticalGraphicsInc/cesium/blob/master/CONTRIBUTORS.md" } ],