This guide is for those who want to contribute code to
getting-started-inner-source. This guide describes how to set up your development environment so that you can build and testgetting-started-inner-source.
In order to work with getting-started-inner-source as a developer, we recommend you:
- Know JavaScript, since
getting-started-inner-sourceis written in JavaScript. - Are familiar with Node.js, since
getting-started-inner-sourceruns on it. - Feel comfortable with command-line programs.
- Understand unit tests and why they're important.
If that sounds like you, then continue reading to get started.
Before you can build and test getting-started-inner-source, you must install and configure the following products on your development machine:
-
Git and/or the GitHub app (for MacOS or Windows)
Why:
getting-started-inner-sourceis hosted on GitHub and uses Git for source control. In order to obtain the source code, you must first install Git on your system. Instructions for installing and setting up Git can be found at https://help.github.com/articles/set-up-git. -
Node.js, (version specified in the engines field of
package.json)Why:
getting-started-inner-sourceuses Node.js modules to generate tables of contents, version, and publish documentation. -
NPM (which installs with Node.js) or Yarn
Why:
NPM and Yarn install and update
getting-started-inner-source'sthird-party dependencies.
Fork and clone the getting-started-inner-source repository:
-
Sign in to your GitHub account or sign up for a (free) GitHub account.
-
Fork the main
getting-started-inner-sourcerepository (aka, "origin"). -
Clone your fork of the
getting-started-inner-sourcerepository and define anupstreamremote pointing back to thegetting-started-inner-sourcerepository that you forked in the first place.# Clone your GitHub repository: git clone git@github.com:<owner>/getting-started-inner-source.git # Go to the repository's root directory: cd getting-started-inner-source # Add the main GitHub repository as an upstream remote # to your repository: git remote add upstream https://github.com/owner/repo.git
Next, install the JavaScript modules needed to build and test getting-started-inner-source:
# Install all project dependencies (package.json)
npm installView all getting-started-inner-source dependencies.
getting-started-inner-source requires the following dependencies to operate.
| Dependency | Description | Version | License | Type |
|---|---|---|---|---|
| adr@1.0.7 | 轻量级架构记录工具 - Command-line tools for working with Architecture Decision Records | 1.0.7 | MIT | production |
| npm@6.0.0 | a package manager for JavaScript | 6.0.0 | Artistic-2.0 | production |
getting-started-inner-source uses the the following dependencies to build, test, or deploy:
| Dependency | Description | Version | License | Type |
|---|---|---|---|---|
| @semantic-release/changelog@1.0.1 | Set of semantic-release plugins for creating or updating a changelog file | 1.0.1 | MIT | dev |
| @semantic-release/git@3.0.1 | Set of semantic-release plugins to publish to a git repository | 3.0.1 | MIT | dev |
| @semantic-release/npm@3.0.2 | Set of semantic-release plugins to publish to a npm registry | 3.0.2 | MIT | dev |
| ajv@6.2.0 | Another JSON Schema Validator | 6.2.0 | MIT | dev |
| ajv-keywords@3.1.0 | Custom JSON-Schema keywords for Ajv validator | 3.1.0 | MIT | dev |
| commitplease@3.2.0 | Validates strings as commit messages | 3.2.0 | MIT | dev |
| eslint@4.18.1 | An AST-based pattern checker for JavaScript. | 4.18.1 | MIT | dev |
| eslint-config-scanjs@1.0.0-beta4 | umbrella config to get scanjs-like functionality from eslint | 1.0.0-beta4 | MPL-2.0 | dev |
| eslint-config-standard@11.0.0 | JavaScript Standard Style - ESLint Shareable Config | 11.0.0 | MIT | dev |
| eslint-config-xo-space@0.18.0 | ESLint shareable config for XO with 2-space indent | 0.18.0 | MIT | dev |
| eslint-plugin-import@2.9.0 | Import with sanity. | 2.9.0 | MIT | dev |
| eslint-plugin-jsdoc@3.5.0 | JSDoc linting rules for ESLint. | 3.5.0 | BSD-3-Clause | dev |
| eslint-plugin-json@1.2.0 | Lint JSON files | 1.2.0 | ISC | dev |
| eslint-plugin-no-unsafe-innerhtml@1.0.16 | custom ESLint rule to disallows unsafe innerHTML, outerHTML and insertAdjacentHTML | 1.0.16 | MPL-2.0 | dev |
| eslint-plugin-no-unsanitized@3.0.0 | ESLint rule to disallow unsanitized code | 3.0.0 | MPL-2.0 | dev |
| eslint-plugin-node@6.0.1 | Additional ESLint's rules for Node.js | 6.0.1 | MIT | dev |
| eslint-plugin-promise@3.6.0 | Enforce best practices for JavaScript promises | 3.6.0 | ISC | dev |
| eslint-plugin-scanjs-rules@0.2.1 | ESLint plugin that contains ScanJS rules | 0.2.1 | MPL-2.0 | dev |
| eslint-plugin-security@1.4.0 | Security rules for eslint | 1.4.0 | Apache-2.0 | dev |
| eslint-plugin-standard@3.0.1 | ESlint Plugin for the Standard Linter | 3.0.1 | MIT | dev |
| eslint-plugin-unicorn@4.0.2 | Various awesome ESLint rules | 4.0.2 | MIT | dev |
| eslint-plugin-xss@0.1.9 | Validates XSS related issues of mixing HTML and non-HTML content in variables. | 0.1.9 | ISC | dev |
| fixpack@2.3.1 | cli tool that cleans up package.json files. | 2.3.1 | MIT | dev |
| markdown-magic@0.1.20 | Automatically update markdown files with content from external sources | 0.1.20 | MIT | dev |
| markdown-magic-dependency-table@1.3.2 | Generate table of information about dependencies automatically in markdown | 1.3.2 | MIT | dev |
| markdown-magic-install-command@1.3.1 | Print install command for markdown file | 1.3.1 | MIT | dev |
| markdown-magic-package-scripts@1.2.1 | Print list of scripts in package.json with descriptions | 1.2.1 | MIT | dev |
| nsp@3.2.1 | The Node Security (nodesecurity.io) command line interface | 3.2.1 | Apache-2.0 | dev |
| semantic-release@13.4.1 | Automated semver compliant package publishing | 13.4.1 | MIT | dev |
npm run docs
Your test suites must pass within coverage thresholds before your pull request will be reviewed on GitHub.
To run tests:
$ npm test
# => Run all `getting-started-inner-source` tests on node
$ npm run test:watch
# => Run tests whenever a file changes
getting-started-inner-source uses
- ESLint to evaluate and format source code;
- Fixpack to order all
package.jsonproperties consistently; and - Prettier to format JSON, Markdown, and YAML.
- Standard JS code style
for code clarity and community conventions.
You can both evaluate and format your all sources by running:
$ npm run lint
# => Formats and lints all JavaScript, JSON, Markdown, and
# package.json.You can also format sources by type:
# Evaluate and format JavaScript:
npm run lint:js
# Format JSON:
npm run lint:json
# Clean up the product manifest (package.json):
npm run lint:manifest
# Format all markdown files:
npm run lint:md
commonality/getting-started-inner-sourceuses Travis CI for continuous integration and delivery.
All tests are executed with Continuous Integration services.
- We test on Node.js versions
10,9,8, and7.6.0on Windows, Mac, and Ubuntu operating systems. - PRs will only be merged once all tests pass.
- Travis CI will fail if any of the test suites fails, or a linting rule is violated.
