diff --git a/.circleci/config.yml b/.circleci/config.yml index ff96483d83be..77b4a06c12f9 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -18,7 +18,7 @@ jobs: command: yarn install --offline --frozen-lockfile - run: name: Build packages - command: yarn build + command: yarn lerna run build --scope=carbon-components --include-filtered-dependencies - run: name: Run Continuous Integration checks command: yarn lerna run ci-check --scope carbon-components @@ -64,7 +64,7 @@ jobs: command: yarn install --offline --frozen-lockfile - run: name: Build packages - command: yarn build + command: yarn lerna run build --scope=carbon-components-react --include-filtered-dependencies - run: name: Run Continuous Integration checks command: yarn lerna run ci-check --scope carbon-components-react @@ -74,14 +74,18 @@ jobs: if [ "${CIRCLE_BRANCH}" == "master" ]; then # Install `ibmcloud` CLI curl -fsSL https://clis.ng.bluemix.net/install/linux | sh + # Login and push staging manifest ibmcloud login \ --apikey $CLOUD_API_KEY \ -a https://api.ng.bluemix.net \ - -o carbon-design-system \ - -s production + -o carbon-design-system + + ibmcloud target -s production + ibmcloud cf add-plugin-repo CF-Community https://plugins.cloudfoundry.org ibmcloud cf install-plugin blue-green-deploy -f -r CF-Community + # Default storybook build cd packages/react yarn build-storybook diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index 9d8124736338..b9e08199783e 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -1,34 +1,62 @@ ## Carbon Code of Conduct -This is a place to ask questions, work through any challenges, and share ideas and best practices. The following suggestions and guidelines are intended to make the community easier and more enjoyable to use. +This is a place to ask questions, work through any challenges, and share ideas +and best practices. The following suggestions and guidelines are intended to +make the community easier and more enjoyable to use. ### TLDR; -- **Be respectful & understanding.** Not all of us will agree all the time, but disagreement is no excuse for poor behavior or poor manners. It is important that we resolve disagreements and differing views constructively. +- **Be respectful & understanding.** Not all of us will agree all the time, but + disagreement is no excuse for poor behavior or poor manners. It is important + that we resolve disagreements and differing views constructively. -* **Be welcoming.** We strive to be a community that welcomes and supports people of all backgrounds and identities. +* **Be welcoming.** We strive to be a community that welcomes and supports + people of all backgrounds and identities. ### General -Communication through any of Carbon's channels (GitHub, emails, Twitter, Slack) must be constructive and never resort to personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct. +Communication through any of Carbon's channels (GitHub, emails, Twitter, Slack) +must be constructive and never resort to personal attacks, trolling, public or +private harassment, insults, or other unprofessional conduct. -We promise to extend courtesy and respect to everyone involved in this project, regardless of gender, gender identity, sexual orientation, disability, age, race, ethnicity, religion, or level of experience. We expect anyone contributing to Carbon to do the same. +We promise to extend courtesy and respect to everyone involved in this project, +regardless of gender, gender identity, sexual orientation, disability, age, +race, ethnicity, religion, or level of experience. We expect anyone contributing +to Carbon to do the same. -If any member of the community violates this Code of Conduct, the maintainers of Carbon may take action, including removing issues, comments, and PRs or blocking accounts, as deemed appropriate. +If any member of the community violates this Code of Conduct, the maintainers of +Carbon may take action, including removing issues, comments, and PRs or blocking +accounts, as deemed appropriate. -If you are subjected to or witness unacceptable behavior, or have any other concerns, please communicate with us directly via carbon@us.ibm.com. +If you are subjected to or witness unacceptable behavior, or have any other +concerns, please communicate with us directly via carbon@us.ibm.com. ### Slack -1. Please, no `@here` or `@channel` unless it is a bug that is **breaking production code.** We have communities in many different time zones, and we would hate to disrupt someone not at the office. -2. There's no need to notify the Carbon team that you have made an issue in Carbon's GitHub repositories. We check these several times a day, so we promise we'll address your issue as soon as we can. -3. Reserve direct messages for sensitive discussions, such as privacy, legal, or HR reasons. Otherwise, we encourage posting in public channels so people with the same questions can benefit. -4. If you have a pressing bug fix, it is best to make a PR directly to get your issues addressed. -5. `#carbon-components`: This channel is for questions about Carbon Components only. It is not the place to ask general coding questions. Instead, use a dev community like [StackOverflow](https://stackoverflow.com/). -6. `#carbon-design-system`: Please post any design questions with an in-context screen shot (i.e. screen shot of the whole UI you are designing) with background as to what you are trying to accomplish in this flow. We welcome in-progress work to get community design feedback as well. +1. Please, no `@here` or `@channel` unless it is a bug that is **breaking + production code.** We have communities in many different time zones, and we + would hate to disrupt someone not at the office. +2. There's no need to notify the Carbon team that you have made an issue in + Carbon's GitHub repositories. We check these several times a day, so we + promise we'll address your issue as soon as we can. +3. Reserve direct messages for sensitive discussions, such as privacy, legal, + or HR reasons. Otherwise, we encourage posting in public channels so people + with the same questions can benefit. +4. If you have a pressing bug fix, it is best to make a PR directly to get your + issues addressed. +5. `#carbon-components`: This channel is for questions about Carbon Components + only. It is not the place to ask general coding questions. Instead, use a + dev community like [StackOverflow](https://stackoverflow.com/). +6. `#carbon-design-system`: Please post any design questions with an in-context + screen shot (i.e. screen shot of the whole UI you are designing) with + background as to what you are trying to accomplish in this flow. We welcome + in-progress work to get community design feedback as well.
-If you have suggestions to improve this Code of Conduct, please submit an issue or PR. +If you have suggestions to improve this Code of Conduct, please submit an issue +or PR. -This Code of Conduct was adopted from the [Angular Project](https://github.com/angular/code-of-conduct/blob/master/CODE_OF_CONDUCT.md) and [Todo Open Code of Conduct](http://todogroup.org/opencodeofconduct/). +This Code of Conduct was adopted from the +[Angular Project](https://github.com/angular/code-of-conduct/blob/master/CODE_OF_CONDUCT.md) +and [Todo Open Code of Conduct](http://todogroup.org/opencodeofconduct/). diff --git a/.github/COMPONENT_DOCS_TEMPLATE.md b/.github/COMPONENT_DOCS_TEMPLATE.md index 0511504f3fb0..10a72e97f7a7 100644 --- a/.github/COMPONENT_DOCS_TEMPLATE.md +++ b/.github/COMPONENT_DOCS_TEMPLATE.md @@ -2,7 +2,8 @@ #### Mixins -Mixins specific to { THIS_COMPONENT_NAME } are located in [src/components/{ COMPONENT }/\_mixins.scss](). +Mixins specific to { THIS_COMPONENT_NAME } are located in +[src/components/{ COMPONENT }/\_mixins.scss](). | Name | Params | Description | | ---------- | ----------------- | ----------- | diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 5343c4f19cb3..95400fdf9157 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -5,16 +5,19 @@ Set up your SSH Key GitHub account and install node.js 4 or higher. - [Generating SSH Keys - GitHub](https://help.github.com/articles/generating-ssh-keys/) -- [`nvm` (Node Version Manager)](https://github.com/creationix/nvm) to use the `Node 6`. +- [`nvm` (Node Version Manager)](https://github.com/creationix/nvm) to use the + `Node 6`. -Contributing to carbon-components requires that you can run this repo locally on your computer. +Contributing to carbon-components requires that you can run this repo locally on +your computer. ## Coding style ### Class names -Prefix all class names with `#{$prefix}--` in SCSS, which is replaced with `bx--` by default, -and design systems inheriting Carbon can override. This prefix prevents potential conflicts with class names from the user. +Prefix all class names with `#{$prefix}--` in SCSS, which is replaced with +`bx--` by default, and design systems inheriting Carbon can override. This +prefix prevents potential conflicts with class names from the user. **HTML** @@ -39,7 +42,8 @@ and design systems inheriting Carbon can override. This prefix prevents potentia } ``` -Follow BEM naming convention for classes. Again, the only thing we do differently is prefix all classes with `#{$prefix}--`. +Follow BEM naming convention for classes. Again, the only thing we do +differently is prefix all classes with `#{$prefix}--`. ```scss .#{$prefix}--block @@ -72,28 +76,45 @@ Avoid nesting selectors, this will make it easier to maintain in the future. ### Sass documentation -[SassDoc](http://sassdoc.com) is used to document the Carbon Sass source. SassDoc annotations start each line with `///`; do not use `///` in non-SassDoc comments. +[SassDoc](http://sassdoc.com) is used to document the Carbon Sass source. +SassDoc annotations start each line with `///`; do not use `///` in non-SassDoc +comments. -For consistency, capitalize types (used in `@type`, `@param`, `@return`) and descriptions (used in `@param`, `@return`, `@deprecated`, `@example`, `@link`). +For consistency, capitalize types (used in `@type`, `@param`, `@return`) and +descriptions (used in `@param`, `@return`, `@deprecated`, `@example`, `@link`). The following annotations are used: **Required annotations** -- [Description](http://sassdoc.com/annotations/#description) - can be one line or multiple lines -- [`@access`](http://sassdoc.com/annotations/#access) - `public` or `private`, where public items make up our public API -- [`@group`](http://sassdoc.com/annotations/#group) - typically a package or component name -- [`@type`](http://sassdoc.com/annotations/#type) - allowed on **variables**, (e.g. `Map`, `Color`, `Number`) -- [`@param`](http://sassdoc.com/annotations/#parameter) - allowed on **functions** and **mixins**, include the type, name, and description, with a default value if there is one (e.g. `@param {Map} $breakpoints [$carbon--grid-breakpoints] - A map of breakpoints where the key is the name`) -- [`@return`](http://sassdoc.com/annotations/#return) - allowed on **functions**, include the type and description (e.g. `@return {Number} In px`) -- [`@alias`](http://sassdoc.com/annotations/#alias) - do not include the `$` if aliasing a variable -- [`@content`](http://sassdoc.com/annotations/#content) - allowed on **mixins**, describe the usage of content -- [`@deprecated`](http://sassdoc.com/annotations/#deprecated) - context around possible replacements or when the item will no longer be available +- [Description](http://sassdoc.com/annotations/#description) - can be one line + or multiple lines +- [`@access`](http://sassdoc.com/annotations/#access) - `public` or `private`, + where public items make up our public API +- [`@group`](http://sassdoc.com/annotations/#group) - typically a package or + component name +- [`@type`](http://sassdoc.com/annotations/#type) - allowed on **variables**, + (e.g. `Map`, `Color`, `Number`) +- [`@param`](http://sassdoc.com/annotations/#parameter) - allowed on + **functions** and **mixins**, include the type, name, and description, with a + default value if there is one (e.g. + `@param {Map} $breakpoints [$carbon--grid-breakpoints] - A map of breakpoints where the key is the name`) +- [`@return`](http://sassdoc.com/annotations/#return) - allowed on + **functions**, include the type and description (e.g. + `@return {Number} In px`) +- [`@alias`](http://sassdoc.com/annotations/#alias) - do not include the `$` if + aliasing a variable +- [`@content`](http://sassdoc.com/annotations/#content) - allowed on **mixins**, + describe the usage of content +- [`@deprecated`](http://sassdoc.com/annotations/#deprecated) - context around + possible replacements or when the item will no longer be available **Optional annotations** -- [`@example`](http://sassdoc.com/annotations/#example) - if the usage isn't straight forward or there are multiple use cases -- [`@link`](http://sassdoc.com/annotations/#link) - if there's a related link to reference +- [`@example`](http://sassdoc.com/annotations/#example) - if the usage isn't + straight forward or there are multiple use cases +- [`@link`](http://sassdoc.com/annotations/#link) - if there's a related link to + reference **Examples** @@ -129,7 +150,8 @@ $interactive-01: map-get($carbon--theme, interactive-01) !default; ### Start a new `block` or `element`? -A nested element can use a new block name as long as the styles are independent of the parent. +A nested element can use a new block name as long as the styles are independent +of the parent. ```html
@@ -137,8 +159,9 @@ A nested element can use a new block name as long as the styles are independent
``` -:point_up: The `#{$prefix}--component-button` class implies that this button has independent styles from its parent. -Generally, it's preferred to start a new block. +:point_up: The `#{$prefix}--component-button` class implies that this button has +independent styles from its parent. Generally, it's preferred to start a new +block. ### Red flags @@ -162,8 +185,10 @@ button - button.config.js ``` -Also note that all variants of a component can live in a single HBS, SCSS and JS file respectively. -For example, while there are many button variants (primary, secondary, etc.), they're all contained in those single source files in the button folder. +Also note that all variants of a component can live in a single HBS, SCSS and JS +file respectively. For example, while there are many button variants (primary, +secondary, etc.), they're all contained in those single source files in the +button folder. ## Defining markups for components and their variants @@ -174,29 +199,51 @@ There are two ways to define markups for components and their variants: ### Defining markup with no conditional or data interpolations -Defining markup with no conditional or data interpolation is as easy as adding a `.hbs` file to the component directory. No `.config.js` file in the component directory is required in this case. One thing to note is that If there is a `.hbs` file whose basename is exactly the same as the component name, other `.hbs` files has to be in `componentname--variantname.hbs` format. +Defining markup with no conditional or data interpolation is as easy as adding a +`.hbs` file to the component directory. No `.config.js` file in the component +directory is required in this case. One thing to note is that If there is a +`.hbs` file whose basename is exactly the same as the component name, other +`.hbs` files has to be in `componentname--variantname.hbs` format. ### Defining markup with conditionals or data interpolations -Defining markup with conditionals or data interpolations requires creating `.config.js` file, which is a [JavaScript module format of Fractal configuration](https://fractal.build/guide/core-concepts/configuration-files.html#configuration-file-formats), in component directory. `.hbs` files are rendered with the data given via `context` property in `variants[n]` (below). +Defining markup with conditionals or data interpolations requires creating +`.config.js` file, which is a +[JavaScript module format of Fractal configuration](https://fractal.build/guide/core-concepts/configuration-files.html#configuration-file-formats), +in component directory. `.hbs` files are rendered with the data given via +`context` property in `variants[n]` (below). -Supported [properties in `.config.js`](https://fractal.build/guide/components/configuration-reference.html#component-properties) are the following: +Supported +[properties in `.config.js`](https://fractal.build/guide/components/configuration-reference.html#component-properties) +are the following: -- [`default`](https://fractal.build/guide/components/configuration#default): The default variant name -- [`variants`](https://fractal.build/guide/components/configuration#variant-properties) - An array of objects, supporting the following properties: +- [`default`](https://fractal.build/guide/components/configuration#default): The + default variant name +- [`variants`](https://fractal.build/guide/components/configuration#variant-properties) - + An array of objects, supporting the following properties: - `name`: The variant name - `label`: The variant name shown in dev env UI - `notes`: A short explainer the variant shown in dev env UI - `context`: The data used for rendering `.hbs` - - `view`: The basename of the `.hbs` file for variant markup (Unlike [default Fractal environment](https://fractal.build/guide/components/configuration#view), this property should point to the basename of a `.hbs` file under `demo` directory or `src` directory, _without_ its path) - - `preview`: The basename of the `.hbs` file for the markup that lays out the variant markup, in "full render" mode (Unlike [default Fractal environment](https://fractal.build/guide/components/configuration#preview), this property should point to the basename of a `.hbs` file under `demo` directory or `src` directory, _without_ `@` symbol) - - `meta`: Some metadata. Carbon vanilla development environment reads the following ones specifically: + - `view`: The basename of the `.hbs` file for variant markup (Unlike + [default Fractal environment](https://fractal.build/guide/components/configuration#view), + this property should point to the basename of a `.hbs` file under `demo` + directory or `src` directory, _without_ its path) + - `preview`: The basename of the `.hbs` file for the markup that lays out the + variant markup, in "full render" mode (Unlike + [default Fractal environment](https://fractal.build/guide/components/configuration#preview), + this property should point to the basename of a `.hbs` file under `demo` + directory or `src` directory, _without_ `@` symbol) + - `meta`: Some metadata. Carbon vanilla development environment reads the + following ones specifically: - `linkOnly`: Only full-page demo is allowed - `useIframe`: Use of `