From b2a3acea0d0f66028c9ce5fad02d4ecc64abf70c Mon Sep 17 00:00:00 2001 From: Israel Lavi Date: Tue, 7 Aug 2018 10:54:17 +0300 Subject: Initial commit. Adding files needed for Linux Foundation. Change-Id: I9f2b4851a5ae01f83800c7f8bab8608a2221c730 Issue-ID: SDC-1608 Signed-off-by: Israel Lavi --- wiki/Adding_a_new_component.md | 100 +++++++++++++++++++++ wiki/Adding_a_new_component_to_storybook.md | 62 +++++++++++++ wiki/Contribution_guide.md | 30 +++++++ .../Deploying_storybook_to_a_forks_github_pages.md | 13 +++ wiki/Understanding_project_build.md | 76 ++++++++++++++++ wiki/home.md | 1 + 6 files changed, 282 insertions(+) create mode 100644 wiki/Adding_a_new_component.md create mode 100644 wiki/Adding_a_new_component_to_storybook.md create mode 100644 wiki/Contribution_guide.md create mode 100644 wiki/Deploying_storybook_to_a_forks_github_pages.md create mode 100644 wiki/Understanding_project_build.md create mode 100644 wiki/home.md (limited to 'wiki') diff --git a/wiki/Adding_a_new_component.md b/wiki/Adding_a_new_component.md new file mode 100644 index 0000000..7309597 --- /dev/null +++ b/wiki/Adding_a_new_component.md @@ -0,0 +1,100 @@ +# Adding a new component +To add a new component to this project, and to its showcase powered by [storybook](https://github.com/storybooks/storybook), follow the following simple guidelines. Throughout this guide, we will pretend to be adding a new component called *myComponent*. + +Note: the project is build of 3 different projects: +1. [onap-ui-common](https://github.com/onap-sdc/onap-ui-common) - contains HTML and SCSS files for all components +2. [onap-ui-angular](https://github.com/onap-sdc/onap-ui-angular) - contains Angular components according to the HTML defined in onap-ui-common +3. [onap-ui-react](https://github.com/onap-sdc/onap-ui-react) - contains React components according to the HTML defined in onap-ui-common + +## 1. Create a new feature branch +In your forked repository, after making sure your `master` branch is synced with original repository's `master`, create a new branch named feature/myComponent. +Note: This should be done in all 3 projects: onap-ui-common, onap-ui-angular, onap-ui-react + +## 2. Add .html and .scss files (onap-ui-common only) +* Under the components directory (onap-ui-common) at the root of the project, create a new directory with the name of your component. +* Create **one** .scss file, declaring the appropriate classes and rules for your component, following the css guidelines in terms of hierarchy and naming methodology. Make sure to name your file by the following convention: **_myComponent.scss**. +* Create **multiple** .html files, one for each of the possible styles of your component, using the classes you declared in the .scss file. + +## 3. Import your .scss file (onap-ui-common only) +Add the appropriate import for your new .scss file in scss/_components.scss: +```scss +@import ../components/myComponent.scss; +``` + +## 4. Implement the React and Angular2 components (onap-ui-angular / onap-ui-react) +The next step is to use your html and scss structure and implement them in React and Angular. + +### React +See [onap-ui-react](https://github.com/onap-sdc/onap-ui-react) project for more details + +### Angular +Create a new folder with component name under src/angular. Inside the folder create component module, ts file and HTML file. +Keep the names according to the rule: **MyComponent.component.ts**, and implement the component. Make sure to exporting your component. + +Note: due to issues compiling the HTML files, all HTML files as extension of .ts + +**Create component typescript file** +```js +// src/angular/MyComponent/my-component.component.ts + +import { Component, Input } from "@angular/core"; +import { template } from "./my-component.component.html"; + +@Component({ + selector: "my-component", + template: template +}) + +export class MyComponent { + @Input() public testId: string; + @Input() public text: string; + + constructor() {} + + public onClick = (e): void => { + // Do something + } + +} +``` + +**Create component HTML file** +```js +// src/angular/MyComponent/my-component.component.html.ts +export const template = ` + +`; +``` + +**Create component module file** +```js +// src/angular/MyComponent/my-component.module.ts +import { NgModule } from "@angular/core"; +import { MyComponent } from "./my-component.component"; + +@NgModule({ + declarations: [MyComponent], + imports: [], + exports: [MyComponent], +}) +export class MyComponentModule {} +``` + +**Export the component in src\angular\components.ts file** + +```js +// src/angular/components.ts + +export { MyComponent } from "./src/angular/my-component/my-component.component"; +``` + +## 5. Add your component to storybook +See [Adding a component to storybook](https://github.com/onap-sdc/onap-ui-angular/wiki/Adding-a-new-component-to-storybook). + +## 6. Push and create a new pull request +Push your branch to your fork's origin/feature/myComponent, and create a new pull request from your fork to the original repo. + +## 7. Release if needed +If your changes require a new release to `npm`, please contact the administrators. + +Hurray! your component is live at the [showcase](https://onap-sdc.github.io/onap-ui-angular/), and if it was released can be consumed from npm. diff --git a/wiki/Adding_a_new_component_to_storybook.md b/wiki/Adding_a_new_component_to_storybook.md new file mode 100644 index 0000000..3861b7e --- /dev/null +++ b/wiki/Adding_a_new_component_to_storybook.md @@ -0,0 +1,62 @@ +# Adding a new component to storybook + +To add your new component to storybook, follow the steps in this document. Make sure that you added your component to the library as described in [Adding a new component](https://github.com/onap-sdc/onap-ui-angular/wiki/Adding-a-new-component). We will continue from where we took off, pretending to add our new component, MyComponent, to storybook. + +## 1. Create the story +under **stories/angular** directory at the root of the project, create a new file called `mycomponents.stories.ts`. + +Example of component story file: +```js +import { storiesOf } from '@storybook/angular'; +import { withKnobs, text, number, boolean, array, select, color, date, button } from '@storybook/addon-knobs'; +import { withNotes } from '@storybook/addon-notes'; +import { action, configureActions } from '@storybook/addon-actions'; +import { moduleMetadata } from '@storybook/angular'; +import { MyComponent } from '../../src/angular/components'; + +storiesOf('Category|MyComponent', module) + .addDecorator(withKnobs) + .addDecorator(withNotes) + .addDecorator( + moduleMetadata({ + declarations: [ + MyComponent + ], + imports: [] + }) + ) + .add('Category name', () => { + const _text = text('text', 'Simple component'); + const _checked = boolean('checked', false); + const _disabled = boolean('disabled', false); + const _testId = text('testId', 'smalpe-test-id'); + const _checkedChange = text('*(checkedChange)', 'Event throws when checked changed, see in Action logger tab.'); + + return { + props: { + checkedChange: action('MyComponent value changed '), + _text, _checked, _disabled, _testId + }, + template: ` + + + ` + } + }, + { notes: `

My Component

+ Full example of my component. + Use the KNOBS tab to change values.` + } +) +``` + +## 3. Run storybook +The final step is to run storybook and make sure everything is working. just run `npm run storybook` to get a local server running, and direct your browser to the outputted address. + +If you want to deploy storybook to your fork's github pages, follow [Deploying storybook to a fork's github pages](https://github.com/onap-sdc/onap-ui-common/wiki/Deploying-storybook-to-a-fork's-github-pages). diff --git a/wiki/Contribution_guide.md b/wiki/Contribution_guide.md new file mode 100644 index 0000000..3ce4f8b --- /dev/null +++ b/wiki/Contribution_guide.md @@ -0,0 +1,30 @@ +# Contribution guide +Contribution to this project will be accepted **only** by following this guide. + +## 1. Fork +Fork this repository to your own Github account. + +## 2. Clone +Run `git clone https://github.com/yourusername/onap-ui-angular.git` to clone your forked repository on your local machine. Don't forget to run `npm install` in your freshly cloned repository to install all dependencies. + +## 3. Configure travis +Follow the [Deploying storybook to a fork's github pages] to configure your personal travis settings. + +## 4. Make sure your fork is synced +This repository has a hook (powered by [backstroke](http:/backstroke.us)), that upon each change to the `master` branch sends a pull request with the changes to all of its forks. Make sure to monitor these pull request and keep your fork in sync. + +## 5. Workflow +Whenever starting to work on your new contribution, first of all make sure your fork is synced (no pending pull requests). An important rule to follow is to *never do any work and commits on your master branch*. Your fork's `master` should serve only as a copy of the original. +Workflow is as following (on your local clone of course): +* `git checkout master` +* `git pull` (after you made sure your fork's master is synced) +* `git checkout -b your-branch` +* Do some work and commit your changes +* If there were changes on the original repo while you were doing your work: + * Merge relevant pull request into your fork + * `git checkout master` + * `git pull` + * `git checkout your-branch` + * `git rebase master` +* Push your branch to your fork +* Create a new pull request from your branch to the original repo's master (NOTE: **do not create a pull request to your fork's master**) diff --git a/wiki/Deploying_storybook_to_a_forks_github_pages.md b/wiki/Deploying_storybook_to_a_forks_github_pages.md new file mode 100644 index 0000000..4c4be46 --- /dev/null +++ b/wiki/Deploying_storybook_to_a_forks_github_pages.md @@ -0,0 +1,13 @@ +# Deploying storybook to a fork's github pages +By following the steps in this document, you will be able to deploy storybook to your own fork's github pages (useful for a staging environment that can be reviewed by a designer). + +## 1. Enable the repository in your travis homepage +After you've forked this repository, go to [travis](https://travis-ci.org), and sign in with your Github account. Then go to your profile page by clicking your avatar in the top right corner. Inside the profile page, filck the onap-ui-angular repository switch on. Travis is now enabled for your repository. + +## 2. Define environment variables +Go to your repository setting in travis. There are two environment variables you need to define: +* GITHUB_TOKEN: your personal access token. If you don't know how to create one, follow this [guide](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/). When you create your token, use 'repo' permissions only. Make sure the 'Display value in build log' switch is off, so that your token will be encrypted. +* DEPLOY: set this variable to 1 if you want builds to trigger deployment, 0 otherwise. This time, make sure the 'Display value in build log' switch is on. NOTE: setting this to 1 will trigger a deployment on **every** branch you push to your repo, not only on master (because no work should be done on your fork's master anyways.) + +## 3. Check that travis is working +Push a new branch to your fork and check that travis ran a build on your branch and deployed it. The deployment address should be https://*username*.github.io/onap-ui-angular diff --git a/wiki/Understanding_project_build.md b/wiki/Understanding_project_build.md new file mode 100644 index 0000000..253d83f --- /dev/null +++ b/wiki/Understanding_project_build.md @@ -0,0 +1,76 @@ +# Understanding project build + +Details about building the project for deploying as NPM module + +Great document clarify build process: https://medium.com/@trekhleb/how-to-create-aot-jit-compatible-angular-4-library-with-external-scss-html-templates-9da6e68dac6e + +## Two main builds: +1. Build onap-ui-angular project as NPM module (npm run build), so 3rd parties can use it. +2. Build onap-ui-angular for storybook (npm run storybook:build), to show the components in github pages. + +## package.json scripts +build: main build of the project +build:ngc: run ngc and comoile the typescript files (using NGC) +build:umd: build 4 UMD bundled files using webpack +storybook: start the storybook server +storybook:prebuild: ? +storybook:build: build the storybook code for using in github pages + + +## Exclude Angular core from the bundle + +It might be pretty obvious but we must keep in mind that we’re writing library for Angular project. Since project itself must have Angular core as a dependency the library should not include Angular sources in the bundles it produces. To do so we need to setup peer dependencies in our package.json file. +```js +{ + ... + "peerDependencies": { + "@angular/common": "^6.0.3", + "@angular/core": "^6.0.3" + } + ... +} +``` + +## Compile using NGC + +Running node_modules/.bin/ngc -p tsconfig-aot.json + +Some important notes regarding tsconfig-aot.json file: +```js +{ + "compilerOptions": { + "target": "es5", // Specifying ES standard + "module": "es2015", + "sourceMap": true, // Ask tsc to generate *.map.js files + "declaration": true, // Ask tsc to generate *.d.ts files + "outDir": "dist", // Specify output folder for the files + ... + }, + "files": [ // Specify input file for tsc/ngc + "./src/angular/index.ts" + ], + "angularCompilerOptions": { // Angular compiler specific config + "genDir": "dist", + "skipTemplateCodegen": true, // Don't produce *.ngfactory.ts + ... + } +} +``` + +## Bundle using WEBPACK + +We use webpack to create UMD (Universal Module Definition) file. This format is for delivering library as a bundle since it ultimately implements both AMD and CommonJS formats. In a result our bundle may be consumed even on the back-end by Node. + +Webpack will create 4 files: +1. index.umd.js - Main javascript file, unminified. +2. index.umd.min.js - For consumers convenience minified version of the bundle to decrease download time for the user. +3. index.umd.js.map - For debuging the bundle: JavaScript SourceMaps. +4. index.umd.min.js.map - Same map file minified. + +## Build files summary + +1. package.json - main build file, define the dependencies and node scripts, also data for deployment. +2. tsconfig-aot.json - used by NGC to compile .ts file to .js files. + + + diff --git a/wiki/home.md b/wiki/home.md new file mode 100644 index 0000000..5d5edf9 --- /dev/null +++ b/wiki/home.md @@ -0,0 +1 @@ +Welcome to the onap-ui-angular wiki! -- cgit 1.2.3-korg