Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Top-level script command tweaks and README updates #2071

Merged
merged 10 commits into from
May 6, 2024
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions .github/workflows/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -100,8 +100,8 @@ jobs:
exitOnceUploaded: true # Do not wait for test results
exitZeroOnChanges: true # Option to prevent the workflow from failing

# Lint and Test
- run: npm run concurrently-lint-test
# Validate (Lint and Test)
- run: npm run validate

# Run Lighthouse audit (from any push)
- name: Performance Audit with Lighthouse CI
Expand All @@ -118,6 +118,8 @@ jobs:
run: |
echo print files with changes:
git diff-index --ignore-space-at-eol --stat HEAD
echo print diff or blank if no changes:
git diff
echo exit with error if there are changes.
git diff-index --quiet --ignore-space-at-eol --stat HEAD

Expand Down
46 changes: 25 additions & 21 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,28 @@
# Contributing to Nimble

⚠️ **Note**: Nimble doesn't yet support normal open source fork-pull workflows (see https://github.com/ni/nimble/issues/634). To contribute pull requests you must be granted access to the repo. See the [Community section of the README](/README.md#community) to get in touch if you need access.
## Getting started

To submit changes to Nimble, the first step is to build the monorepo which requires the following to be setup:

- Sync down a copy of the nimble repository
- Note: For one-off small contributions you can consider using a fork-pull workflow. However [fork-pull workflows are not yet supported](https://github.com/ni/nimble/issues/634) for substantial development. For substantial development you should be added as a Contributor to the repository. See the [`README.md` Community section](/README.md#community) to get in touch if you need Contributor permissions.
- Install Node.js version 20+ (run `node --version`) and npm version 10+ (run `npm --version`) which can be downloaded from https://nodejs.org/en/download/
- Install .NET 6 SDK (`6.0.418 <= version < 7`) which can be downloaded from https://dotnet.microsoft.com/en-us/download
- Run `dotnet --info` to verify the required version of the SDK is installed. A `v6` install is required, but it's fine if later versions are installed too.

From the `nimble` directory:

1. Run `npm install`
2. Run `npm run build`
3. Run `npm run storybook` to view the components in Storybook

Note: As you make style changes to components you will need to refresh your browser window to see the effect.

For Visual Studio Code users:

- Nimble includes
rajsite marked this conversation as resolved.
Show resolved Hide resolved

Now that you can build the monorepo see the `CONTRIBUTING.md` for the packages you would like to contribute to.

## Repository overview

Expand All @@ -20,24 +42,6 @@ This repository uses the following tooling. See below for more info.
- [Nimble Components Figma Library](https://www.figma.com/file/PO9mFOu5BCl8aJvFchEeuN/Nimble_Components?node-id=1295%3A77205&mode=dev)
- [Nimble technologies walkthrough video](https://nio365.sharepoint.com/:v:/s/SystemLinkDesignSystem/EY4c8IRUechPgBkomuIDwwEB2rl66Tg2CJxY0nfPsqSb8g?e=fWViGm) (NI internal)

## Getting started

First step in development is to build the monorepo which requires the following to be installed:

- Node.js version 20+ (run `node --version`) and npm version 10+ (run `npm --version`) which can be downloaded from https://nodejs.org/en/download/
- .NET 6 SDK (`6.0.418 <= version < 7`) which can be downloaded from https://dotnet.microsoft.com/en-us/download
- Run `dotnet --info` to verify the required version of the SDK is installed. A `v6` install is required, but it's fine if later versions are installed too.

From the `nimble` directory:

1. Run `npm install`
2. Run `npm run build` (Alternatively in Visual Studio Code **Terminal » Run Build Task…** [Mac: `cmd+shift+B` Windows: `ctrl+shift+B`])
3. Run `npm run storybook -w @ni/nimble-components` to view the components in Storybook

**Note**: You will need to refresh your browser window to see style changes made in source.

Now that you can build the monorepo see the `CONTRIBUTING.md` for the packages you would like to contribute to.

## Develop new components

### Adding a new component
Expand Down Expand Up @@ -84,11 +88,11 @@ When generating a change file, follow these guidelines:
If a beachball publish command fails on the pipeline so packages are partially published, perform the following steps to get the repo in a good state:

1. Create a branch from main which should still have change files from the failed publish and, if applicable, fix the underlying issue in the branch.
2. In the repo root run `npm run beachball-sync`. Beachball will:
2. In the repo root run `npm run sync`. Beachball will:
- Find the latest packages that were published successfully to npm.
- Update the `package.json` for each of those packages to align with the latest published version. It also handles cross-dependencies, i.e. angular shows the latest version of components as its dependency.
- Note: It does not handle packages that are not published to npm at all. For example, you need to manually check nuget.org for `NimbleBlazor`'s published version and update the `package.json`.
3. Commit the changes from `npm run beachball-sync` and run `npm run change` for those changes.
3. Commit the changes from `npm run sync` and run `npm run change` for those changes.
4. Submit a PR for the branch and merge.

### Dependency Review
Expand Down
66 changes: 37 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,58 +5,66 @@

# Nimble

The NI Nimble Design System: Styled UI components for NI applications.

[![storybook page](https://img.shields.io/badge/storybook%20documentation-white.svg?logo=storybook)](https://ni.github.io/nimble/storybook)
[![example angular app](https://img.shields.io/badge/example%20angular%20application-dd0031.svg?logo=angular)](https://ni.github.io/nimble/storybook/example-client-app)
[![example blazor app](https://img.shields.io/badge/example%20blazor%20application-572b8a.svg?logo=blazor)](https://ni.github.io/nimble/storybook/blazor-client-app/wwwroot)
[![component status page](https://img.shields.io/badge/✔-component%20status%20table-074023.svg)](https://nimble.ni.dev/storybook/?path=/docs/component-status--docs)

If you are at NI, lucky you! **Reach out to ask questions** via Microsoft Teams on the Design System [`General` channel](https://teams.microsoft.com/l/team/19%3awo8vmMKMsHfltKXxc0bczZo-X4JlQSV5VxpaRJdh13k1%40thread.tacv2/conversations?groupId=9ee065d7-3898-4245-82f6-76e86084b8b1&tenantId=87ba1f9a-44cd-43a6-b008-6fdb45a5204e) or via NI Stack Overflow with the [`nimble` tag](https://ni.stackenterprise.co/questions/tagged/813).

If you are outside NI, we want to hear from you too! See how to reach out in the [**Community**](#community) section below.

## Getting Started

See the corresponding `Getting Started` section for the general-use Nimble packages:

[![Nimble Angular NPM version and repo link](https://img.shields.io/npm/v/@ni/nimble-angular.svg?label=@ni/nimble-angular)](https://www.npmjs.com/package/@ni/nimble-angular)
[![Nimble Blazor Nuget version and repo link](https://img.shields.io/nuget/v/NimbleBlazor.svg?label=NimbleBlazor)](https://www.nuget.org/packages/NimbleBlazor)
[![Nimble Components NPM version and repo link](https://img.shields.io/npm/v/@ni/nimble-components.svg?label=@ni/nimble-components)](https://www.npmjs.com/package/@ni/nimble-components)
[![Nimble Tokens NPM version and repo link](https://img.shields.io/npm/v/@ni/nimble-tokens.svg?label=@ni/nimble-tokens)](https://www.npmjs.com/package/@ni/nimble-tokens)

The NI Nimble Design System: styled UI components for NI applications.
- **[`@ni/nimble-angular`](/angular-workspace/projects/ni/nimble-angular/)** - Handy bindings to the Nimble components for Angular applications.
- **[`@ni/nimble-blazor`](/packages/nimble-blazor/)** - Handy bindings to the Nimble components for Blazor applications.
rajsite marked this conversation as resolved.
Show resolved Hide resolved
- **[`@ni/nimble-components`](/packages/nimble-components/)** - Nimble components to be used by [any type of application](https://custom-elements-everywhere.com/).
rajsite marked this conversation as resolved.
Show resolved Hide resolved

[![storybook page](https://img.shields.io/badge/storybook-white.svg?logo=storybook)](https://ni.github.io/nimble/storybook)
[![example angular app](https://img.shields.io/badge/example%20angular%20app-dd0031.svg?logo=angular)](https://ni.github.io/nimble/storybook/example-client-app)
[![example blazor app](https://img.shields.io/badge/example%20blazor%20app-572b8a.svg?logo=blazor)](https://ni.github.io/nimble/storybook/blazor-client-app/wwwroot)

If you are at NI, lucky you! **Reach out to ask questions directly in the [Design System Teams channel](https://teams.microsoft.com/l/team/19%3awo8vmMKMsHfltKXxc0bczZo-X4JlQSV5VxpaRJdh13k1%40thread.tacv2/conversations?groupId=9ee065d7-3898-4245-82f6-76e86084b8b1&tenantId=87ba1f9a-44cd-43a6-b008-6fdb45a5204e).**
The context-specific Spright packages:

## Getting Started
[![Spright Angular NPM version and repo link](https://img.shields.io/npm/v/@ni/spright-angular.svg?label=@ni/spright-angular)](https://www.npmjs.com/package/@ni/spright-angular)
[![Spright Blazor Nuget version and repo link](https://img.shields.io/nuget/v/SprightBlazor.svg?label=SprightBlazor)](https://www.nuget.org/packages/SprightBlazor)
[![Spright Components NPM version and repo link](https://img.shields.io/npm/v/@ni/spright-components.svg?label=@ni/spright-components)](https://www.npmjs.com/package/@ni/spright-components)

This repository contains the source for the following packages:
- [`@ni/spright-angular`](/angular-workspace/projects/ni/spright-angular/) - Handy bindings to the Spright components for Angular applications.
rajsite marked this conversation as resolved.
Show resolved Hide resolved
- [`@ni/spright-blazor`](/packages/nimble-blazor/) - Handy bindings to the Spright components for Blazor applications.
rajsite marked this conversation as resolved.
Show resolved Hide resolved
- [`@ni/spright-components`](/packages/spright-components/) - Spright components to be used by [any type of application](https://custom-elements-everywhere.com/).

- **[`@ni/nimble-angular`](/angular-workspace/projects/ni/nimble-angular/)** - styled Angular components for use in NI Angular applications
- **[`@ni/nimble-blazor`](/packages/nimble-blazor/)** - styled Blazor components for use in NI Blazor applications
- **[`@ni/nimble-components`](/packages/nimble-components/)** - styled web components for use in other applications (also used by `nimble-angular` and `nimble-blazor`)
- **[`@ni/nimble-tokens`](/packages/nimble-tokens/)** - design tokens used by the component packages
The utility packages:

And some additional utility packages:
- [`@ni/jasmine-parameterized`](/packages/jasmine-parameterized/) - a utility for writing [Jasmine](https://jasmine.github.io/) parameterized tests
- [`@ni/xliff-to-json-converter`](/packages/xliff-to-json-converter/) - a utility to convert translation files from XLIFF to JSON for Angular localization
[![Nimble Tokens NPM version and repo link](https://img.shields.io/npm/v/@ni/nimble-tokens.svg?label=@ni/nimble-tokens)](https://www.npmjs.com/package/@ni/nimble-tokens)
[![Jasmine parameterized NPM version and repo link](https://img.shields.io/npm/v/@ni/jasmine-parameterized.svg?label=@ni/jasmine-parameterized)](https://www.npmjs.com/package/@ni/jasmine-parameterized)
[![XLIFF to JSON Converter for Angular NPM version and repo link](https://img.shields.io/npm/v/@ni/xliff-to-json-converter.svg?label=@ni/xliff-to-json-converter)](https://www.npmjs.com/package/@ni/xliff-to-json-converter)

Consult the `README.md` for each package to learn more, including how to use it in an application.
- [`@ni/nimble-tokens`](/packages/nimble-tokens/) - Base design tokens used by the Nimble and Spright component packages.
- [`@ni/jasmine-parameterized`](/packages/jasmine-parameterized/) - a utility for writing [Jasmine](https://jasmine.github.io/) parameterized tests.
- [`@ni/xliff-to-json-converter`](/packages/xliff-to-json-converter/) - a utility to convert translation files from XLIFF to JSON for Angular localization.

The above packages follow [Semantic Versioning](https://semver.org). Consult the `CHANGELOG.md` for each package to see the changes in each version, including instructions for adapting your application in response to breaking changes.

## Community

We welcome feedback and contributions!

The fastest way to ask questions is to [join the discussion on Teams](https://teams.microsoft.com/l/team/19%3awo8vmMKMsHfltKXxc0bczZo-X4JlQSV5VxpaRJdh13k1%40thread.tacv2/conversations?groupId=9ee065d7-3898-4245-82f6-76e86084b8b1&tenantId=87ba1f9a-44cd-43a6-b008-6fdb45a5204e) (accessible to NI employees only). You can also start a discussion on GitHub by [filing an issue using the Discussion template](https://github.com/ni/nimble/issues/new/choose).

## Requesting New Components and Features
The fastest way to ask questions is to [join the discussion on Teams](https://teams.microsoft.com/l/team/19%3awo8vmMKMsHfltKXxc0bczZo-X4JlQSV5VxpaRJdh13k1%40thread.tacv2/conversations?groupId=9ee065d7-3898-4245-82f6-76e86084b8b1&tenantId=87ba1f9a-44cd-43a6-b008-6fdb45a5204e) or the [NI Stack Overflow](https://ni.stackenterprise.co/questions/tagged/813) (accessible to NI employees only). You can also start a discussion on GitHub by filing an issue using the [**🎙 Discussion**](https://github.com/ni/nimble/issues/new/choose) template.

Is Nimble missing a component that your team needs? Search the [issues list](https://github.com/ni/nimble/issues) to see if it's on our radar. If an issue exists already, comment with your use cases. If no issue exists yet, file a new one using the **Feature request** template.
### Requesting New Components and Features

## Filing Bugs
Is Nimble missing a component that your team needs? Check the [Component Status](https://ni.github.io/nimble/storybook/?path=/docs/component-status--docs) page and search the [Issues](https://github.com/ni/nimble/issues) list to see if it's on our radar. If an issue exists already, comment with your use cases. If no issue exists yet, file a new one using the [**🙋 Feature Request**](https://github.com/ni/nimble/issues/new/choose) template.

To report a bug with an existing component, file an issue using the **Bug report** template.
### Filing Bugs

## Learning

- [Architecture](/docs/Architecture.md) - Architecture of the design system packages and monorepo
To report a bug with an existing component, file an issue using the [**🐛 Bug Report**](https://github.com/ni/nimble/issues/new/choose) template.

## Contributing

See `Getting Started` in [`Contributing.md`](/CONTRIBUTING.md#getting-started) to get started with building the monorepo.

## Component Status

View status of components that are completed and on the roadmap in the [Component Status](https://ni.github.io/nimble/storybook/?path=/docs/component-status--docs) page.
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
rajsite marked this conversation as resolved.
Show resolved Hide resolved
"type": "none",
"comment": "Command and readme updates",
"packageName": "@ni/nimble-components",
"email": "rajsite@users.noreply.github.com",
"dependentChangeType": "none"
}
17 changes: 9 additions & 8 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,22 @@
"private": true,
"description": "The NI Nimble Design System Monorepo",
"scripts": {
"postinstall": "patch-package && npm run playwright:setup",
"playwright:setup": "playwright install --with-deps",
"postinstall": "patch-package && npm run playwright-setup",
"playwright-setup": "playwright install --with-deps",
rajsite marked this conversation as resolved.
Show resolved Hide resolved
"build": "npm run build --workspaces --if-present",
"format": "npm run format --workspaces --if-present",
"pack": "npm run pack --workspaces --if-present",
"change": "beachball change",
"check": "beachball check --changehint \"Run 'npm run change' to generate a change file\"",
"sync": "beachball sync",
"invoke-publish": "cross-env-shell beachball publish --yes --access public --message \\\"applying package updates [skip ci]\\\" -n $NPM_SECRET_TOKEN",
"performance": "npm run performance --workspaces --if-present",
"beachball-sync": "beachball sync",
"lint-sequential": "npm run lint --workspaces --if-present",
"test-sequential": "npm run test --workspaces --if-present",
"lint-concurrently": "npm run lint-concurrently -w packages/nimble-components",
"test-concurrently": "npm run test-concurrently -w packages/nimble-components",
"concurrently-lint-test": "concurrently --timings --group \"npm:lint-sequential\" \"npm:test-sequential\" \"npm:lint-concurrently\" \"npm:test-concurrently\""
"validate": "concurrently --timings --group \"npm:validate:*\"",
"validate:lint:sequential": "npm run lint --workspaces --if-present",
"validate:test:sequential": "npm run test --workspaces --if-present",
"validate:lint-concurrent:nimble-components": "npm run lint-concurrent -w packages/nimble-components",
"validate:test-concurrent:nimble-components": "npm run test-concurrent -w packages/nimble-components",
"storybook": "concurrently -n nimble,spright,storybook \"npm run build-components:watch -w @ni/nimble-components\" \"npm run build-components:watch -w @ni/spright-components\" \"npm run start -w @ni-private/storybook\""
},
"repository": {
"type": "git",
Expand Down
4 changes: 2 additions & 2 deletions packages/nimble-components/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
"description": "Styled web components for the NI Nimble Design System",
"scripts": {
"build": "npm run generate-icons && npm run generate-workers && npm run build-components && npm run bundle-components && npm run generate-scss",
"lint-concurrently": "concurrently --timings --group \"npm:eslint\" \"npm:prettier\"",
"lint-concurrent": "concurrently --timings --group \"npm:eslint\" \"npm:prettier\"",
"format": "npm run eslint-fix && npm run prettier-fix",
"eslint": "eslint .",
"eslint-fix": "eslint src --fix",
Expand Down Expand Up @@ -44,7 +44,7 @@
"test-webkit:verbose": "karma start karma.conf.verbose.js --browsers=WebkitHeadless --single-run --skip-tags SkipWebkit",
"test-webkit:watch": "karma start karma.conf.js --browsers=WebkitHeadless --skip-tags SkipWebkit --watch-extensions js",
"test-webkit": "karma start karma.conf.js --browsers=WebkitHeadless --single-run --skip-tags SkipWebkit",
"test-concurrently": "concurrently --timings --group \"npm:test-chrome:verbose\" \"npm:test-firefox:verbose\""
"test-concurrent": "concurrently --timings --group \"npm:test-chrome:verbose\" \"npm:test-firefox:verbose\""
},
"repository": {
"type": "git",
Expand Down
2 changes: 1 addition & 1 deletion packages/storybook/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
"generate-icons": "npm run generate-icons:bundle && npm run generate-icons:run",
"generate-icons:bundle": "rollup --bundleConfigAsCjs --config build/generate-icons/rollup.config.js",
"generate-icons:run": "node build/generate-icons/dist/index.js",
"start": "storybook dev -p 6006",
"start": "storybook dev --quiet -p 6006",
"lint": "npm run eslint && npm run prettier",
"format": "npm run eslint-fix && npm run prettier-fix",
"eslint": "eslint src",
Expand Down
Loading