From 2441d51093565b83a9a03d3e3c4f71ca86db7a32 Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Mon, 20 Nov 2017 14:05:47 +0800 Subject: [PATCH 1/3] add remark lint to ensure fenced codeblocks are formatted properly. --- .remarkrc | 6 ++++++ package.json | 4 +++- 2 files changed, 9 insertions(+), 1 deletion(-) create mode 100644 .remarkrc diff --git a/.remarkrc b/.remarkrc new file mode 100644 index 000000000000..a64b15136a41 --- /dev/null +++ b/.remarkrc @@ -0,0 +1,6 @@ +{ + "plugins": [ + ["remark-lint-code-block-style", "fenced"], + ["remark-lint-fenced-code-flag"] + ] +} \ No newline at end of file diff --git a/package.json b/package.json index d42bf431af31..f65d1fd73429 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,8 @@ "husky": "^0.14.3", "minimist": "^1.2.0", "nugget": "^2.0.1", + "remark-cli": "^4.0.0", + "remark-preset-lint-markdown-style-guide": "^2.1.1", "request": "^2.68.0", "standard": "^8.4.0", "standard-markdown": "^4.0.0", @@ -48,7 +50,7 @@ "lint-js": "standard && cd spec && standard", "lint-cpp": "python ./script/cpplint.py", "lint-py": "python ./script/pylint.py", - "lint-docs": "npm run lint-js-in-markdown && npm run create-typescript-definitions", + "lint-docs": "remark docs -qf && npm run lint-js-in-markdown && npm run create-typescript-definitions", "lint-js-in-markdown": "standard-markdown docs", "create-api-json": "electron-docs-linter docs --outfile=out/electron-api.json --version=$npm_package_version", "create-typescript-definitions": "npm run create-api-json && electron-typescript-definitions --in=out/electron-api.json --out=out/electron.d.ts", From 435e027dc3ff8af963129a97f8dafe931bc6be53 Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Mon, 20 Nov 2017 14:18:24 +0800 Subject: [PATCH 2/3] fix linting for fenced codeblocks only (see electron/electronjs.org#868) --- docs/api/chrome-command-line-switches.md | 2 +- docs/api/menu.md | 4 +-- docs/api/remote.md | 2 +- docs/api/sandbox-option.md | 12 ++++--- docs/api/session.md | 2 +- .../development/build-instructions-windows.md | 2 +- docs/development/chromium-development.md | 28 ++++++++++----- docs/development/releasing.md | 8 ++--- docs/development/setting-up-symbol-server.md | 6 ++-- .../source-code-directory-structure.md | 4 +-- docs/faq.md | 18 +++++----- docs/styleguide.md | 2 +- docs/tutorial/application-distribution.md | 6 ++-- docs/tutorial/electron-versioning.md | 34 +++++++++---------- docs/tutorial/quick-start.md | 6 ++-- docs/tutorial/testing-on-headless-ci.md | 2 +- docs/tutorial/windows-store-guide.md | 6 ++-- 17 files changed, 79 insertions(+), 65 deletions(-) diff --git a/docs/api/chrome-command-line-switches.md b/docs/api/chrome-command-line-switches.md index 4aa809b02c14..0f3d243ed272 100644 --- a/docs/api/chrome-command-line-switches.md +++ b/docs/api/chrome-command-line-switches.md @@ -112,7 +112,7 @@ A comma-separated list of servers for which integrated authentication is enabled For example: -``` +```bash --auth-server-whitelist='*example.com, *foobar.com, *baz' ``` diff --git a/docs/api/menu.md b/docs/api/menu.md index 05d826b99c18..f16c0127b800 100644 --- a/docs/api/menu.md +++ b/docs/api/menu.md @@ -315,7 +315,7 @@ Template: Menu: -``` +```sh - 1 - 2 - 3 @@ -338,7 +338,7 @@ Template: Menu: -``` +```sh - --- - a - b diff --git a/docs/api/remote.md b/docs/api/remote.md index 2abb2a843110..f5bc80d577c5 100644 --- a/docs/api/remote.md +++ b/docs/api/remote.md @@ -146,7 +146,7 @@ of the main process. e.g. -``` +```sh project/ ├── main │   ├── foo.js diff --git a/docs/api/sandbox-option.md b/docs/api/sandbox-option.md index 1b35ef6256dd..c49c4bb0adbe 100644 --- a/docs/api/sandbox-option.md +++ b/docs/api/sandbox-option.md @@ -78,7 +78,7 @@ Note that it is not enough to call code runs after it is possible to make changes to chromium sandbox settings. The switch must be passed to electron on the command-line: -``` +```sh electron --enable-sandbox app.js ``` @@ -151,10 +151,12 @@ Important things to notice in the preload script: To create a browserify bundle and use it as a preload script, something like the following should be used: - browserify preload/index.js \ - -x electron \ - -x fs \ - --insert-global-vars=__filename,__dirname -o preload.js +```sh + browserify preload/index.js \ + -x electron \ + -x fs \ + --insert-global-vars=__filename,__dirname -o preload.js +``` The `-x` flag should be used with any required module that is already exposed in the preload scope, and tells browserify to use the enclosing `require` function diff --git a/docs/api/session.md b/docs/api/session.md index d3f128ff5de4..a08543cc89c4 100644 --- a/docs/api/session.md +++ b/docs/api/session.md @@ -140,7 +140,7 @@ option is ignored and `pacScript` configuration is applied. The `proxyRules` has to follow the rules below: -``` +```sh proxyRules = schemeProxies[";"] schemeProxies = ["="] urlScheme = "http" | "https" | "ftp" | "socks" diff --git a/docs/development/build-instructions-windows.md b/docs/development/build-instructions-windows.md index e0d9fc280728..f199796282c7 100644 --- a/docs/development/build-instructions-windows.md +++ b/docs/development/build-instructions-windows.md @@ -114,7 +114,7 @@ Make sure you have the latest Visual Studio update installed. If building under Cygwin, you may see `bootstrap.py` failed with following error: -``` +```bash Assertion failed: ((handle))->activecnt >= 0, file src\win\pipe.c, line 1430 Traceback (most recent call last): diff --git a/docs/development/chromium-development.md b/docs/development/chromium-development.md index 6804f3482ece..abf36ee42351 100644 --- a/docs/development/chromium-development.md +++ b/docs/development/chromium-development.md @@ -18,7 +18,9 @@ See also [V8 Development](v8-development.md) It is possible to debug Chromium with Electron by passing `--build_debug_libcc` to the bootstrap script: - $ ./script/bootstrap.py -d --build_debug_libcc +```bash +$ ./script/bootstrap.py -d --build_debug_libcc +``` This will download and build libchromiumcontent locally, similarly to the `--build_release_libcc`, but it will create a shared library build of @@ -27,13 +29,17 @@ libchromiumcontent and won't strip any symbols, making it ideal for debugging. When built like this, you can make changes to files in `vendor/libchromiumcontent/src` and rebuild quickly with: - $ ./script/build.py -c D --libcc +```bash +$ ./script/build.py -c D --libcc +``` When developing on linux with gdb, it is recommended to add a gdb index to speed up loading symbols. This doesn't need to be executed on every build, but it is -recommended to do it at least once to index most shared libraries: +recommended to do it at least once to index most shared libraries: - $ ./vendor/libchromiumcontent/src/build/gdb-add-index ./out/D/electron +```bash +$ ./vendor/libchromiumcontent/src/build/gdb-add-index ./out/D/electron +``` Building libchromiumcontent requires a powerful machine and takes a long time (though incremental rebuilding the shared library component is fast). With an @@ -54,13 +60,17 @@ several libchromiumcontent build trees on the same machine(to work on different branches for example), it is recommended to set the variable to speed up the download of Chromium source. For example: - $ mkdir ~/.chromium-git-cache - $ LIBCHROMIUMCONTENT_GIT_CACHE=~/.chromium-git-cache ./script/bootstrap.py -d --build_debug_libcc +```bash +$ mkdir ~/.chromium-git-cache +$ LIBCHROMIUMCONTENT_GIT_CACHE=~/.chromium-git-cache ./script/bootstrap.py -d --build_debug_libcc +``` If the bootstrap script is interrupted while using the git cache, it will leave the cache locked. To remove the lock, delete the files ending in `.lock`: - $ find ~/.chromium-git-cache/ -type f -name '*.lock' -delete +```bash +$ find ~/.chromium-git-cache/ -type f -name '*.lock' -delete +``` It is possible to share this directory with other machines by exporting it as SMB share on linux, but only one process/machine can be using the cache at a @@ -70,6 +80,8 @@ not work perfectly in a network. On Windows, SMBv2 has a directory cache that will cause problems with the git cache script, so it is necessary to disable it by setting the registry key - HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Lanmanworkstation\Parameters\DirectoryCacheLifetime +```bash +HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Lanmanworkstation\Parameters\DirectoryCacheLifetime +``` to 0. More information: https://stackoverflow.com/a/9935126 diff --git a/docs/development/releasing.md b/docs/development/releasing.md index a72d7d151fb9..9d379b918472 100644 --- a/docs/development/releasing.md +++ b/docs/development/releasing.md @@ -73,7 +73,7 @@ Tips: For a `patch` release, use the following format: -``` +```sh ## Bug Fixes * Fixed a cross-platform thing. #123 @@ -95,7 +95,7 @@ For a `patch` release, use the following format: For a `minor` release, e.g. `1.8.0`, use this format: -``` +```sh ## Upgrades - Upgraded from Node `oldVersion` to `newVersion`. #123 @@ -118,7 +118,7 @@ For a `minor` release, e.g. `1.8.0`, use this format: ``` ### Major releases -``` +```sh ## Upgrades - Upgraded from Chromium `oldVersion` to `newVersion`. #123 @@ -147,7 +147,7 @@ For a `minor` release, e.g. `1.8.0`, use this format: ### Beta releases Use the same formats as the ones suggested above, but add the following note at the beginning of the changelog: -``` +```sh **Note:** This is a beta release and most likely will have have some instability and/or regressions. Please file new issues for any bugs you find in it. diff --git a/docs/development/setting-up-symbol-server.md b/docs/development/setting-up-symbol-server.md index 100384d4d3e8..7f55e2ace8d2 100644 --- a/docs/development/setting-up-symbol-server.md +++ b/docs/development/setting-up-symbol-server.md @@ -29,7 +29,7 @@ your symbol path (**Note:** you can replace `c:\code\symbols` with any writable directory on your computer, if you'd prefer a different location for downloaded symbols): -``` +```powershell SRV*c:\code\symbols\*https://electron-symbols.githubapp.com ``` @@ -37,7 +37,7 @@ Set this string as `_NT_SYMBOL_PATH` in the environment, using the Windbg menus, or by typing the `.sympath` command. If you would like to get symbols from Microsoft's symbol server as well, you should list that first: -``` +```powershell SRV*c:\code\symbols\*http://msdl.microsoft.com/download/symbols;SRV*c:\code\symbols\*https://electron-symbols.githubapp.com ``` @@ -50,7 +50,7 @@ SRV*c:\code\symbols\*http://msdl.microsoft.com/download/symbols;SRV*c:\code\symb Type the following commands in Windbg to print why symbols are not loading: -``` +```powershell > !sym noisy > .reload /f electron.exe ``` diff --git a/docs/development/source-code-directory-structure.md b/docs/development/source-code-directory-structure.md index 4af519120ee3..19b9017646ea 100644 --- a/docs/development/source-code-directory-structure.md +++ b/docs/development/source-code-directory-structure.md @@ -9,7 +9,7 @@ to understand the source code better. ## Structure of Source Code -``` +```sh Electron ├── atom/ - C++ source code. | ├── app/ - System entry code. @@ -85,7 +85,7 @@ git submodule update --init --recursive If you find yourself running this command often, you can create an alias for it in your `~/.gitconfig` file: -``` +```sh [alias] su = submodule update --init --recursive ``` diff --git a/docs/faq.md b/docs/faq.md index d8c74e07c605..92b6260faefb 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -2,17 +2,17 @@ ## Why am I having trouble installing Electron? -When running `npm install electron`, some users occasionally encounter +When running `npm install electron`, some users occasionally encounter installation errors. -In almost all cases, these errors are the result of network problems and not -actual issues with the `electron` npm package. Errors like `ELIFECYCLE`, -`EAI_AGAIN`, `ECONNRESET`, and `ETIMEDOUT` are all indications of such -network problems. The best resolution is to try switching networks, or +In almost all cases, these errors are the result of network problems and not +actual issues with the `electron` npm package. Errors like `ELIFECYCLE`, +`EAI_AGAIN`, `ECONNRESET`, and `ETIMEDOUT` are all indications of such +network problems. The best resolution is to try switching networks, or just wait a bit and try installing again. -You can also attempt to download Electron directly from -[electron/electron/releases](https://github.com/electron/electron/releases) +You can also attempt to download Electron directly from +[electron/electron/releases](https://github.com/electron/electron/releases) if installing via `npm` is failing. ## When will Electron upgrade to latest Chrome? @@ -134,7 +134,7 @@ delete window.module; When using Electron's built-in module you might encounter an error like this: -``` +```sh > require('electron').webFrame.setZoomFactor(1.0) Uncaught TypeError: Cannot read property 'setZoomLevel' of undefined ``` @@ -151,7 +151,7 @@ console.log(require.resolve('electron')) and then check if it is in the following form: -``` +```sh "/path/to/Electron.app/Contents/Resources/atom.asar/renderer/api/lib/exports/electron.js" ``` diff --git a/docs/styleguide.md b/docs/styleguide.md index 5ebf047cdd30..7793893424b5 100644 --- a/docs/styleguide.md +++ b/docs/styleguide.md @@ -168,7 +168,7 @@ The optional arguments are notated by square brackets `[]` surrounding the optio as well as the comma required if this optional argument follows another argument: -``` +```sh required[, optional] ``` diff --git a/docs/tutorial/application-distribution.md b/docs/tutorial/application-distribution.md index ea4735871a39..b1c43474c00b 100644 --- a/docs/tutorial/application-distribution.md +++ b/docs/tutorial/application-distribution.md @@ -80,7 +80,7 @@ file's name. The structure of a renamed app would be like: -``` +```text MyApp.app/Contents ├── Info.plist ├── MacOS/ @@ -140,7 +140,7 @@ we appreciate your help. 2. Create a new S3 bucket and create the following empty directory structure: - ``` + ```sh - atom-shell/ - symbols/ - dist/ @@ -157,7 +157,7 @@ we appreciate your help. * `CI` - Set to `true` or else it will fail * `GITHUB_TOKEN` - set it to the same as `ELECTRON_GITHUB_TOKEN` * `SURF_TEMP` - set to `C:\Temp` on Windows to prevent path too long issues - * `TARGET_ARCH` - set to `ia32` or `x64` + * `TARGET_ARCH` - set to `ia32` or `x64` 4. In `script/upload.py`, you _must_ set `ELECTRON_REPO` to your fork (`MYORG/electron`), especially if you are a contributor to Electron proper. diff --git a/docs/tutorial/electron-versioning.md b/docs/tutorial/electron-versioning.md index 5ea77d631121..f606620c0dbf 100644 --- a/docs/tutorial/electron-versioning.md +++ b/docs/tutorial/electron-versioning.md @@ -6,7 +6,7 @@ If you've been using Node and npm for a while, you are probably aware of [Semant Semantic versions are always made up of three numbers: -``` +```sh major.minor.patch ``` @@ -18,7 +18,7 @@ Semantic version numbers are bumped (incremented) using the following rules: A simple mnemonic for remembering this scheme is as follows: -``` +```sh breaking.feature.fix ``` @@ -35,11 +35,11 @@ This system had a number of drawbacks, such as: - New bugs could be introduced into a new patch version because patch versions added features - It didn't follow SemVer so it could confuse consumers - It wasn't clear what the differences between stable and beta builds were -- The lack of a formalized stabilization process and release schedule lead to sporadic releases and betas that could last several months +- The lack of a formalized stabilization process and release schedule lead to sporadic releases and betas that could last several months ## Version 2 and Beyond -From version 2.0.0, Electron will attempt to adhere to SemVer and follow a +From version 2.0.0, Electron will attempt to adhere to SemVer and follow a release schedule and stabilization process similar to that of Chromium. ### Version Change Rules @@ -67,11 +67,11 @@ will be prefixed with a caret `^` in package.json: } ``` -The [caret semver range](https://docs.npmjs.com/misc/semver#caret-ranges-123-025-004) -allows minor- and patch-level changes to be installed, i.e. non-breaking +The [caret semver range](https://docs.npmjs.com/misc/semver#caret-ranges-123-025-004) +allows minor- and patch-level changes to be installed, i.e. non-breaking features and bug fixes. -Alternatively, a more conservative approach is to use the +Alternatively, a more conservative approach is to use the [tilde semver range](https://docs.npmjs.com/misc/semver#tilde-ranges-123-12-1) `~`, which will only allow patch-level upgrades, i.e. bug fixes. @@ -88,28 +88,28 @@ Here are some important points to call out: - A new release is performed approximately weekly. - Minor versions are branched off of master for stabilization. - The stabilization period is approximately weekly. -- Important bug fixes are cherry-picked to stabilization branches after landing +- Important bug fixes are cherry-picked to stabilization branches after landing in master. -- Features are not cherry picked; a minor version should only get *more stable* +- Features are not cherry picked; a minor version should only get *more stable* with its patch versions. -- There is little difference in the release schedule between a major and minor +- There is little difference in the release schedule between a major and minor release, other than the risk/effort it may take for third parties to adopt -- Chromium updates will be performed as fast as the team can manage. In an ideal - world this would happen every 6 weeks to align with +- Chromium updates will be performed as fast as the team can manage. In an ideal + world this would happen every 6 weeks to align with [Chromium's release schedule][Chromium release]. -- Excluding exceptional circumstances, only the previous stable build will +- Excluding exceptional circumstances, only the previous stable build will get backported bug fixes. ### The Beta Process -Electron relies on its consumers getting involved in stabilization. The short -target stabilization period and rapid release cadence was designed for shipping +Electron relies on its consumers getting involved in stabilization. The short +target stabilization period and rapid release cadence was designed for shipping security and bug fixes out fast and to encourage the automation of testing. -You can install the beta by specifying the `beta` dist tag when installing via +You can install the beta by specifying the `beta` dist tag when installing via npm: -``` +```sh npm install electron@beta ``` diff --git a/docs/tutorial/quick-start.md b/docs/tutorial/quick-start.md index 835a75a9775f..3c5728d8ea93 100644 --- a/docs/tutorial/quick-start.md +++ b/docs/tutorial/quick-start.md @@ -183,13 +183,13 @@ $ ./node_modules/.bin/electron . #### Windows -``` +```bash $ .\node_modules\.bin\electron . ``` #### Node v8.2.0 and later -``` +```bash $ npx electron . ``` @@ -212,7 +212,7 @@ $ ./electron/electron your-app/ #### Windows -``` +```bash $ .\electron\electron.exe your-app\ ``` diff --git a/docs/tutorial/testing-on-headless-ci.md b/docs/tutorial/testing-on-headless-ci.md index 557c358b12bf..62220bf1915f 100644 --- a/docs/tutorial/testing-on-headless-ci.md +++ b/docs/tutorial/testing-on-headless-ci.md @@ -23,7 +23,7 @@ commands with `xvfb-maybe` and the little tool will automatically configure xvfb, if required by the current system. On Windows or macOS, it will simply do nothing. -``` +```sh ## On Windows or macOS, this just invokes electron-mocha ## On Linux, if we are in a headless environment, this will be equivalent ## to xvfb-run electron-mocha ./test/*.js diff --git a/docs/tutorial/windows-store-guide.md b/docs/tutorial/windows-store-guide.md index 609ade80136c..436549638c1f 100644 --- a/docs/tutorial/windows-store-guide.md +++ b/docs/tutorial/windows-store-guide.md @@ -36,7 +36,7 @@ requirements: Then, go and install the `electron-windows-store` CLI: -``` +```sh npm install -g electron-windows-store ``` @@ -48,7 +48,7 @@ any module you don't actually need will just increase your application's size. The output should look roughly like this: -``` +```text ├── Ghost.exe ├── LICENSE ├── content_resources_200_percent.pak @@ -79,7 +79,7 @@ From an elevated PowerShell (run it "as Administrator"), run and output directories, the app's name and version, and confirmation that `node_modules` should be flattened. -``` +```powershell electron-windows-store ` --input-directory C:\myelectronapp ` --output-directory C:\output\myelectronapp ` From c122852f09426c9305fbea47a79cf08c11123198 Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Tue, 21 Nov 2017 16:07:26 +0800 Subject: [PATCH 3/3] make verbose execute and non verbose execute do the same things --- script/lib/util.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/script/lib/util.py b/script/lib/util.py index 053023dad09d..492c9a411caa 100644 --- a/script/lib/util.py +++ b/script/lib/util.py @@ -161,11 +161,11 @@ def safe_mkdir(path): raise -def execute(argv, env=os.environ): +def execute(argv, env=os.environ, cwd=None): if is_verbose_mode(): print ' '.join(argv) try: - output = subprocess.check_output(argv, stderr=subprocess.STDOUT, env=env) + output = subprocess.check_output(argv, stderr=subprocess.STDOUT, env=env, cwd=cwd) if is_verbose_mode(): print output return output @@ -183,7 +183,7 @@ def execute_stdout(argv, env=os.environ, cwd=None): print e.output raise e else: - execute(argv, env) + execute(argv, env, cwd) def electron_gyp():