From 4039c7d904a599c4ddaba2795b3b085e79f9e993 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sun, 29 Dec 2024 01:30:05 +0000 Subject: [PATCH] Update services docs with latest READMEs --- pages/services/API catalog.md | 18 +- pages/services/Frontend components.md | 326 +------------------------ pages/services/Notifications UI.md | 3 +- pages/services/PF Component groups.md | 2 +- pages/services/PF Data view.md | 4 +- pages/services/PF Virtual assistant.md | 37 +-- pages/services/RBAC UI.md | 3 - pages/services/UI starter app.md | 15 -- 8 files changed, 33 insertions(+), 375 deletions(-) diff --git a/pages/services/API catalog.md b/pages/services/API catalog.md index f404863..054e481 100644 --- a/pages/services/API catalog.md +++ b/pages/services/API catalog.md @@ -6,14 +6,12 @@ https://developers.redhat.com/api-catalog/ ## Project structure -The main package is found on [src](./src) and contains the React application for the site itself. +The main package is found on [src](./src) and contains the Next.js application. Other packages includes: - [Common code](./packages/common) shared across other packages. Contains the information about the included APIs. - [Discovery](./packages/discovery) contains a file descriptor and its supporting schemas to describe the contents found in API catalog. It includes the list of the APIs, what group they form part of and their metadata. -- [Prerender](./packages/prerender) is a cli tool to pre-render all the API catalog to increase SEO and make it easier to - be read by bots. - [Sitemap](./packages/sitemap) is a cli tool to create the sitemap.xml of API catalog. The sitemap package is also responsible for generating the [canonical format json file](./public/canonical.json) used by the Search Platform for indexing. - [transform](./packages/transform) is a cli tool to process the [discovery file](./packages/discovery/Discovery.yml) and create typescript code that can be loaded by API Catalog, the resulting code is stored in the @@ -78,7 +76,7 @@ Use `npm install` to install all the project dependencies. ### Running the frontend -Use `npm run start` to start the frontend application. +Use `npm run dev` to start the frontend application. ### Running the discovery process @@ -92,12 +90,6 @@ npm run discovery:build && npm run discovery:start -- --skip-api-fetch The sitemap can be re-generated by running: `SITEMAP_BASE_URL=https://my-base-url npm run sitemap`. -### Pre-rendering the site - -To be more bot-friendly we pre-render the whole site to allow it to be crawled. -You can run trigger a local run by building the site `npm run build` and then running `npm run prerender`. The results of the pre-rendering are written in -[build/pre-rendered](./build/pre-rendered) - ## Adding external content Details from each API is extracted from its openapi file to show in the API catalog. Sometimes this is not enough. @@ -125,7 +117,7 @@ This is a list of the support sections, followed by the required file name. - Getting started: `getting-started.md` -## Releasing to Production +## Releasing to Production (Deprecated) We use GitLab tags for deployment to Production. Follow these steps: @@ -150,6 +142,10 @@ We use GitLab tags for deployment to Production. Follow these steps: 4. **Watch the pipeline:** Monitor the pipeline in GitLab's CI/CD > Pipelines section. If successful, your code is deployed to production. +## Releasing to production (new) + +TBD + ## SPAship configuration We require some components that are shared across developers.redhat.com (header and footer). These components needs to be copied (and synchronized from time to time). diff --git a/pages/services/Frontend components.md b/pages/services/Frontend components.md index 4f15829..2a941b0 100644 --- a/pages/services/Frontend components.md +++ b/pages/services/Frontend components.md @@ -1,6 +1,3 @@ -[![Build Status](https://travis-ci.org/RedHatInsights/frontend-components.svg?branch=master)](https://travis-ci.org/RedHatInsights/frontend-components) -[![codecov](https://codecov.io/gh/RedHatInsights/frontend-components/branch/master/graph/badge.svg)](https://codecov.io/gh/RedHatInsights/frontend-components) - # frontend-components Monorepo of Red Hat Cloud services Components for applications in a React.js environment. @@ -15,327 +12,6 @@ Monorepo of Red Hat Cloud services Components for applications in a React.js env * [sources](https://github.com/RedHatInsights/sources-ui/) - Sources Wizard component was moved to Sources UI repository (it's also stored here in `sources_backup` branch) * [testing](https://github.com/RedHatInsights/frontend-components/tree/master/packages/testing) - Testing utilities. * [advisor-components](https://github.com/RedHatInsights/frontend-components/tree/master/packages/advisor-components#readme) - a library of Advisor components (rule content, report details, charts, etc.). -## Contributing to documentation - -To contribute to docs and run the docs developemnt environment, please follow these [guides](https://github.com/RedHatInsights/frontend-components/tree/master/packages/docs/pages/contributing). - -## Treeshaking PF with babel plugin - -Patternfly packages require some enhancements to be done in order to properly treeshake your bundles. You can either use direct imports or plugin that does that for you, there are actually 2 plugins to do this -* [babel-plugin-import](https://www.npmjs.com/package/babel-plugin-import) - easy setup, however not that extensible -* [babel-plugin-transform-imports](https://www.npmjs.com/package/babel-plugin-transform-imports) - harder to setup, but allows custom rules - -Since Patternfly requires a bit of custom settings you should use `babel-plugin-transform-imports`. Change your babel to be JS file `babel.config.js` and add these changes to it - -```JS -// This is required because of how PF is using their css modules. -// This `extensions` will be removed in future, we'll have to come up with some other clever way of doing this -require.extensions['.css'] = () => undefined; -const path = require('path'); -const glob = require('glob'); - -// list of custom named exports, this is just a few, and you should probably update it to fit your project -const mapper = { - TextVariants: 'Text', - DropdownPosition: 'dropdownConstants', - EmptyStateVariant: 'EmptyState', - TextListItemVariants: 'TextListItem', - TextListVariants: 'TextList' -}; - -module.exports = { - presets: [ - // list of your presets goes here - ], - plugins: [ - // your other plugins - [ - 'transform-imports', - { - '@patternfly/react-core': { - transform: (importName) => { - const files = glob.sync( - path.resolve( - __dirname, - // you can use `js` or `esm` - `./node_modules/@patternfly/react-core/dist/js/**/${mapper[ - importName - ] || importName}.js` - ) - ); - if (files.length > 0) { - return files[0].replace(/.*(?=@patternfly)/, ''); - } else { - throw `File with importName ${importName} does not exist`; - } - }, - preventFullImport: false, - skipDefaultConversion: true - } - }, - 'react-core' - ], - [ - 'transform-imports', - { - '@patternfly/react-icons': { - transform: (importName) => - // you can use `js` or `esm` - `@patternfly/react-icons/dist/js/icons/${importName - .split(/(?=[A-Z])/) - .join('-') - .toLowerCase()}`, - preventFullImport: true - } - }, - 'react-icons' - - ] -} - -``` - -#### Jest error - -If you see Jest errors after applying transform-imports plugin you should add to your Jest config - -```JSON -"transformIgnorePatterns": [ "/node_modules/(?!@redhat-cloud-services)" ], -``` - -## Local tasks -Since this is monorepo repository it has some special requirements how to run tasks. This repository is using [lerna](https://github.com/lerna/lerna), so if you have newer version of npm you can run `npx lerna $TASK` where $TASK is one of [lerna commands](https://github.com/lerna/lerna/tree/master/commands). - -These tasks are preconfigured -* `npm start` - will perform start in all packages, you can change the scope by calling `npm start -- --scope=pckg_name` to run start in `pckg_name` -* `npm run build` - will perform build in all packages, you can change the scope by calling `npm start -- --scope=pckg_name` to run start in `pckg_name` -* `npm run clean` - to remove all node modules in root and in packages folder -* `npm run bootstrap` - to install packages correctly (will link local dependencies as well) -* `npm run test` - to run tests locally -* `npm run watch` - similiar to start, but will emit files to disk (good for local links) -* `npm run playground` - to launch local demo on port 8080 - -## Running locally - -There are two ways to test changes from packages in this repository in other applications: Using `npm link` or `yalc`. - -### Using `npm link` - -1. Run `npm install` in the root of the `frontend-components` working copy -2. Change into the directory of the package you are working on, for example `cd packages/components` and run `npm link`* -3. Change into the directory of the application you'd like to include the package and run `npm link @redhat-cloud-services/frontend-components`* - -After these steps the package you want to test should be linked and the last `npm link` command should have returned the paths it linked the package from. - -When linked successfully you can build the package(s) by running either `npm start -- --scope=@redhat-cloud-services/frontend-components` or `npm run build -- --scope=@redhat-cloud-services/frontend-components` in the `frontend-components` working copy. - -Both will build the `@redhat-cloud-services/frontend-components` package, to build all packages run these commands without `-- --scope=@redhat-cloud-services/frontend-components`.* - -Once the packages are built the application the package is linked in should also be able to build and include any changes made locally in the `frontend-components` packages. - -_* Depending on what package you are working on this arguments need to change accordingly._ - -### Using `yalc` - -yalc acts as very simple local repository for your locally developed packages that you want to share across your local environment. - -1. Install [yalc](https://github.com/whitecolor/yalc) globally. e.g. `npm install -g yalc`. -2. Run `npm install` in the root of the `frontend-components` working copy. -3. Change into the directory of the package you are working on, for example `cd packages/components` and run `yalc publish`* -4. Change into the directory of the application you'd like to include the package and run `yalc add @redhat-cloud-services/frontend-components`* - -After these steps the package you want to test should be linked and the `yalc add` command should have returned the paths it linked the package from. - -When added successfully you can build the package(s) by running `npm run build -- --scope=@redhat-cloud-services/frontend-components` in the `frontend-components` working copy and pushing by going into the directory of the package and running `yalc push`. - -`yalc` does not watch the files, but if you would like to do this automatically you can build the package(s) by running: `npm start -- --scope=@redhat-cloud-services/frontend-components` and having a separate terminal that does the local publishing of the packages by running: `watch -n 0.5 yalc publish --push --changed`. This will publish the package only when there are changes. - -To build all packages run these commands without `-- --scope=@redhat-cloud-services/frontend-components`.* - -Once the packages are built the application the package is linked in should also be able to build and include any changes made locally in the `frontend-components` packages. - -To remove the package info from package.json and yalc.lock, run `yalc remove @redhat-cloud-services/frontend-components` to remove a single package; or `yalc remove --all` to remove all packages from a project. - -_* Depending on what package you are working on this arguments need to change accordingly._ - -## Creating new package -If none package suits scope of new changes, we need to create new package by creating folder inside `packages` and running `npm init` in it. - -## Run release - -Webhooks are enabled to trigger releases on travis from comment on merged PR. If you are member of group responsible for releases you can add new commnent to merged PR `Release minor`, `Release bugfix` or `Release` in order to trigger new release. - -You can also draft a release by adding label `release` or `release minor` and once this PR is merged new release will be triggered. - -## Typescript guidelines - -Typescript build has been finally introduced to the repository. All modules will be eventually refactored into typescript. When refactoring, or creating new modules, please follow these instructions when creating types: - -### React components - -1. All component props must be an interface and must be exported. This is required for consuming apps to use features like `omit` or `extends` when developing with typescript. A nice example is generating JSX from array structure, but for some reason, extension/exclustion of the interface is required. - -```TS - -import React from 'react'; -import { AlertProps, AlertVariant } from '@patternfly/react-core'; - -/** - * Custom component wrapper from FEC - * It has a description prop which is mapped to the PF Alert children prop - * */ -interface AlertWrapper extends AlertProps { - description?: string -} - -/** - * Local type which builds on FEC defined type -*/ -interface LocalAlertType extends AlertWrapper { - id: string -} - -const CustomComponent: React.ComponentType = ({ data }) => { - const alertsStructure: LocalAlertType[] = data.map(({ uuid, status, title, message }) => ({ - id: uuid, - variant: status === 500 ? AlertVariant.danger : AlertVariant.info, - title, - description: message - })); - - return alertsStructure.map(({ id, ...props }) => ); -}; - -``` - -2. When creating a wrapper around PF components, always extend original components props. This will ensure that all original props are accepted by your component wrapper. If you have to exclude some original prop, use `Omit` generic. Exclusion might be required because the wrapper is setting a prop by default. - -```TS -import React from 'react'; -import { Alert, AlertProps, AlertVariant } from '@patternfly/react-core'; - -export interface AlertWrapperProps extends Omit { - specificRequiredProp: React.ReactNode -} - -const AlertWrapper: React.FunctionComponent = ({ specificRequiredProp, ...props }) => ( -
- {specificRequiredProp} - -
-); - -export default AlertWrapper; - - -``` - -3. Always export nested types. It can be required by a consumer app when constructing component props. - -```TS -import React from 'react'; -import { Alert, AlertProps, AlertVariant } from '@patternfly/react-core'; - -export type CustomType = 'A' | 'B' | 2 | 'something' -export interface CustomInterface { - a: string, - b?: number -} - -export interface AlertWrapperProps extends Omit { - nestedNonPrimitiveType: CustomType - nestedNonPrimitiveInterface: CustomInterface - nestedNonPrimitiveArray: CustomType[] -} - -const AlertWrapper: React.FunctionComponent = ({ specificRequiredProp, ...props }) => ( -
- {specificRequiredProp} - -
-); - -export default AlertWrapper; - -``` - -### General guidelines - -#### Names - -1. Use PascalCase for type names. -2. Do not use I as a prefix for interface names. -3. Use PascalCase for enum values. -4. Use camelCase for function names. -5. Use camelCase for property names and local variables. -6. Do not use _ as a prefix for private properties. -7. Use whole words in names when possible. - -#### Comments - -1. Always add a short description to exported types. The description is used for generating documentation -2. Use JSDoc style comments for functions, interfaces, enums, and classes. - -```TS -export interface AlertWrapperProps extends Omit { - /** - * Alert id - */ - id: string, - /** - * A content displayed as Patternfly Alert children - */ - description: React.ReactNode -} - -``` - -#### Types - -1. Do not export types/functions unless you need to share it across multiple components. -2. Do not introduce new types/values to the global namespace. -3. Shared types should be defined in types.ts. -4. Within a file, type definitions should come first. - -#### null and undefined - -1. Use undefined. Do not use null. - -#### General Constructs - -For a variety of reasons, we avoid certain constructs, and use some of our own. Among them: - -1. Do not use for..in statements; instead, use ts.forEach, ts.forEachKey and ts.forEachValue. Be aware of their slightly different semantics. -2. Try to use ts.forEach, ts.map, and ts.filter instead of loops when it is not strongly inconvenient. - -#### Style - -1. Use arrow functions over anonymous function expressions. -2. Open curly braces always go on the same line as whatever necessitates them. -3. Parenthesized constructs should have no surrounding whitespace. -4. A single space follows commas, colons, and semicolons in those constructs. For example: -```ts -for (var i = 0, n = str.length; i < 10; i++) { } -if (x < 10) { } -function f(x: number, y: string): void { } -``` -5. Use a single declaration per variable statement -```ts -(i.e. use var x = 1; var y = 2; over var x = 1, y = 2;). -``` - -### Typescript Refactoring -1. Pick a TO DO card from: https://github.com/RedHatInsights/frontend-components/projects/1 and move it to in-progress column. Only modules from the components package should be migrated at the moment. -2. Make sure that all local module dependencies and already migrated to TS. If some of the local dependencies have not been migrated, migrate them first and move the related cards to the in-progress column -``` -import A from './a' // <- not migrated to TS, has to be migrated first -``` -3. Make sure that the `index` file in the appropriate folder is migrated to TS. If not, do it. -```diff -- index.js -+ index.ts -``` -4. Follow typescript guidelines when refactoring -5. Create PR and link it to the project card +## [Please read our contribution guide](./CONTRIBUTING.md) diff --git a/pages/services/Notifications UI.md b/pages/services/Notifications UI.md index ce63ea6..a24df7a 100644 --- a/pages/services/Notifications UI.md +++ b/pages/services/Notifications UI.md @@ -1,7 +1,6 @@ [![Build Status](https://travis-ci.com/RedHatInsights/notifications-frontend.svg?branch=master)](https://travis-ci.com/RedHatInsights/notifications-frontend) - -# notifications-frontend +# notifications-frontend Notifications frontend for Red Hat Insights diff --git a/pages/services/PF Component groups.md b/pages/services/PF Component groups.md index f983025..4bc5c29 100644 --- a/pages/services/PF Component groups.md +++ b/pages/services/PF Component groups.md @@ -4,7 +4,7 @@ This repo contains a set of opinionated react component groups used to standardi ### Migration from [RedHatInsights/frontend-components](https://github.com/RedHatInsights/frontend-components) to [patternfly/react-component-groups](https://github.com/patternfly/react-component-groups) Please see the [migration guide](./migration.md) - + --- ## Contribution guide diff --git a/pages/services/PF Data view.md b/pages/services/PF Data view.md index 013f955..da2fdd3 100644 --- a/pages/services/PF Data view.md +++ b/pages/services/PF Data view.md @@ -26,7 +26,7 @@ export interface MyComponentProps { const useStyles = createUseStyles({ myText: { fontFamily: 'monospace', - fontSize: 'var(--pf-v5-global--icon--FontSize--md)', + fontSize: 'var(--pf-v6-global--icon--FontSize--md)', }, }) @@ -126,7 +126,7 @@ When adding/making changes to a component, always make sure your code is tested: ### Styling: - for styling always use JSS - new classNames should be named in camelCase starting with the name of a given component and following with more details clarifying its purpose/component's subsection to which the class is applied (`actionMenu`, `actionMenuDropdown`, `actionMenuDropdownToggle`, etc.) -- do not use `pf-v5-u-XXX` classes, use CSS variables in a custom class instead (styles for the utility classes are not bundled with the standard patternfly.css - it would require the consumer to import also addons.css) +- do not use `pf-v6-u-XXX` classes, use CSS variables in a custom class instead (styles for the utility classes are not bundled with the standard patternfly.css - it would require the consumer to import also addons.css) --- diff --git a/pages/services/PF Virtual assistant.md b/pages/services/PF Virtual assistant.md index 96569fb..dd6d43c 100644 --- a/pages/services/PF Virtual assistant.md +++ b/pages/services/PF Virtual assistant.md @@ -1,21 +1,21 @@ -# PatternFly Virtual Assistant +# PatternFly ChatBot -This repo contains React Virtual assistant implementation. +This PatternFly extension library provides components based on PatternFly 6 that can be used to build chatbots. --- ## Install -To play with virtual-assistant in your project, run +To use the chatbot extension in your project, run ``` -npm install @patternfly/virtual-assistant --save +npm install @patternfly/chatbot --save ``` Make sure to add the CSS imports as the last import in your index file. The extension is intended to override certain PatternFly component styles. However, if it's not the last import, you may not see these. ``` -import '@patternfly/virtual-assistant/dist/css/main.css'; +import '@patternfly/chatbot/dist/css/main.css'; ``` ## Contribution guide @@ -73,7 +73,7 @@ src - prop names comply with PatternFly components naming standards (`variant`, `onClick`, `position`, etc.) - the API is maximally simplified and all props are provided with a description - it is built on top of existing PatternFly types without prop omitting -- it is well documented using the PatternFly documentation (`/packages/module/patternfly-docs/content/extensions/virtual-assistant/examples/MyComponent/MyComponent.md`) with examples of all possible use cases (`packages/module/patternfly-docs/content/extensions/virtual-assistant/examples/MyComponent/MyComponent[...]Example.tsx`) +- it is well documented using the PatternFly documentation (`/packages/module/patternfly-docs/content/extensions/chatbot/examples/MyComponent/MyComponent.md`) with examples of all possible use cases (`packages/module/patternfly-docs/content/extensions/chatbot/examples/MyComponent/MyComponent[...]Example.tsx`) #### Component API definition example: @@ -88,15 +88,17 @@ export const MyComponent: React.FunctionComponent = ({ customL #### Markdown file example: +Note: You'll need to add any imports required in a component usage file example like MyComponentExample.tsx, below, here as well. + ```` --- section: extensions -subsection: Virtual assistant +subsection: ChatBot id: MyComponent propComponents: ['MyComponent'] --- -import MyComponent from "@patternfly/virtual-assistant/dist/dynamic/MyComponent"; +import MyComponent from "@patternfly/chatbot/dist/dynamic/MyComponent"; ## Component usage @@ -110,6 +112,8 @@ MyComponent has been created to demo contributing to this repository. #### Component usage file example: (`MyComponentExample.tsx`) +Note: You'll need to add any imports required here in the parent folder's markdown file as well. + ``` import React from 'react'; @@ -150,23 +154,24 @@ When adding/making changes to a component, always make sure your code is tested: ## Building for production -- run npm install -- run npm run build +- run `npm install` +- run `npm run build` ## Development -- run npm install -- run npm run start to build and start the development server +- run `npm install` +- run `npm run build` +- run `npm run start` to build and start the development server ## Testing and Linting -- run npm run test to run the tests -- run npm run lint to run the linter +- run `npm run test` to run the tests +- run `npm run lint` to run the linter ## A11y testing -- run npm run build:docs followed by npm run serve:docs, then run npm run test:a11y in a new terminal window to run our accessibility tests. Once the accessibility tests have finished running you can run -- npm run serve:a11y to locally view the generated report +- run `npm run build:docs` followed by `npm run serve:docs`, then run `npm run test:a11y` in a new terminal window to run our accessibility tests. Once the accessibility tests have finished running you can run +- `npm run serve:a11y` to locally view the generated report ## Generating screenshots diff --git a/pages/services/RBAC UI.md b/pages/services/RBAC UI.md index 625f449..9f437a5 100644 --- a/pages/services/RBAC UI.md +++ b/pages/services/RBAC UI.md @@ -10,9 +10,6 @@ This repository is now using experimental workflow checks. Your commits must use ## Getting Started - - - ### Running dev server ```bash diff --git a/pages/services/UI starter app.md b/pages/services/UI starter app.md index 6d0e16b..b1815e1 100644 --- a/pages/services/UI starter app.md +++ b/pages/services/UI starter app.md @@ -1,8 +1,5 @@ -[![Build Status](https://travis-ci.org/RedHatInsights/frontend-starter-app.svg?branch=master)](https://travis-ci.org/RedHatInsights/frontend-starter-app) - # frontend-starter-app - React.js starter app for Red Hat Insights products that includes Patternfly 4 and shared Red Hat cloud service frontend components. ## Alternative @@ -43,15 +40,3 @@ Update `appUrl` string inside `fec.config.js` according to your application URL. ### Testing `npm run verify` will run `npm run lint` (eslint) and `npm test` (Jest) - -## Deploying - -- The starter repo uses Travis to deploy the webpack build to another Github repo defined in `.travis.yml` - - That Github repo has the following branches: - - `ci-beta` (deployed by pushing to `master` or `main` on this repo) - - `ci-stable` (deployed by pushing to `ci-stable` on this repo) - - `qa-beta` (deployed by pushing to `qa-beta` on this repo) - - `qa-stable` (deployed by pushing to `qa-stable` on this repo) - - `prod-beta` (deployed by pushing to `prod-beta` on this repo) - - `prod-stable` (deployed by pushing to `prod-stable` on this repo) -- Travis uploads results to RedHatInsight's [codecov](https://codecov.io) account. To change the account, modify CODECOV_TOKEN on https://travis-ci.com/.