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.

Sign up for GitHub

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

Update README with release changes and contribution clarifications #1436

Merged
merged 5 commits into from
Dec 13, 2024
Merged

Update README with release changes and contribution clarifications #1436

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4e66127
adjust placement of sections and update deployment steps
jamigibbs Dec 12, 2024
3657d7f
grammar update and move version number section
jamigibbs Dec 12, 2024
c945f49
minor clarifying updates
jamigibbs Dec 12, 2024
039f334
formatting
jamigibbs Dec 12, 2024
7100e74
Merge branch 'main' into readme-contributions-storybook
jamigibbs Dec 12, 2024
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
194 changes: 99 additions & 95 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,71 @@
![Publishing workflow](https://github.com/department-of-veterans-affairs/component-library/actions/workflows/publish.yml/badge.svg)
![Latest version](https://img.shields.io/npm/v/@department-of-veterans-affairs/component-library)

This is a monorepo containing two main packages:
This is a monorepo containing the following packages:

- `web-components`
- `react-components`
- `css-library`
- `storybook`
- `design-system-dashboard-cli`

The `core` package is for bundling the `web-components` and `react-components` packages into one for publishing.

The `storybook` package is for the combined story files from each `*-components` package.

The `core` package is for bundling the two main packages into one for publishing. The `storybook` package is for the combined story files from each `*-components` package.
The `design-system-dashboard-cli` package is used to gather metrics on design system usage.

# Running Build via Storybook

1. `cd packages/web-components/`
1. `yarn install`
2. `yarn build`
3. `yarn build-bindings` (build React bindings)
4. `yarn watch:stencil` (optional)
2. `cd ../react-components/`
1. `yarn install`
2. `yarn build`
3. `cd ../core/`
1. `yarn install`
2. `yarn build`
4. `cd ../storybook/`
1. `yarn install`
2. `yarn storybook`

This will allow you to run Storybook locally to view all components

## Running tests for web components

To run unit tests for all components, the commands are:

```bash
yarn test
```

and

```bash
yarn test.watch
```

To test a single file, run:

```bash
npx stencil test --e2e -- src/components/[component-name]/test/[component-name].e2e.ts
```

Replace `[component-name]` with the name of the component you want to test. Optionally, you can add `--watchAll` after `--e2e` to watch the file for changes. For example:

```bash
npx stencil test --e2e --watchAll -- src/components/[component-name]/test/[component-name].e2e.ts
```

Another option is to use wildcards to query for certain tests. For example, to run all tests for the `va-accordion` component, you can run:

```bash
npx stencil test --e2e -- src/components/va-accordion/test/va-accordion-*
```

## Contributing

### Branch naming
Expand All @@ -24,7 +81,11 @@ This repo uses [`Chromatic`](https://www.chromatic.com/) to streamline reviews b

Our web components have linting which checks for hard-coded user-facing strings. At the moment this linting isn't integrated into CI - so you will only see it if you run `yarn lint` or if your editor has ESLint integration through a plugin.

### Local testing with Verdaccio
### Local development

Local development can be done using Storybook by following the complete build steps outlined in [Running Build via Storybook](https://github.com/department-of-veterans-affairs/component-library?tab=readme-ov-file#running-build-via-storybook).

### Local testing in vets-website with Verdaccio
Contributors are encouraged to test their changes in `vets-website` using [Verdaccio](https://verdaccio.org/). What is Verdaccio? From the website:

> Verdaccio is a simple, zero-config-required local private NPM registry. No need for an entire database just to get started…
Expand Down Expand Up @@ -179,6 +240,40 @@ To publish changes from the `web-components` subpackage, make sure the version n

[`yarn version`](https://yarnpkg.com/cli/version) is available to use to make changes in the CLI. To change the version of the package you are working on run one of the following commands: `yarn version major`, `yarn version minor`, or `yarn version patch`. For guidance on which command to use please see below.


### Releasing
Copy link
Contributor Author

@jamigibbs jamigibbs Dec 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I made a few additions to the Release steps because since they were written, we have changed the release PR to increment more than just the core version number. And also a couple of clarifying things with what we do after the release is created (PRs for other repos, etc).


The Design System Team will create a release minimally at the beginning of each sprint (every other Thursday), and may additionally be performed as-needed when critical bug fixes need to go out. Reach out in `#vfs-platform-support` or `#platform-design-system` Slack channel if you have a need for an unscheduled release.

**For Design System Team only:**

1. If you are unsure if a new release should be created, check with the Release Manager and/or the team first.
- The DST Release Manager is the engineer on duty for the weekly support rotation.
2. Create a new `component-library` PR that updates the package.json version in the **packages that updates have been made**:
- `core` (required) - [packages/core/package.json](https://github.com/department-of-veterans-affairs/component-library/blob/main/packages/core/package.json#L4) must be updated for the publishing workflow
- `web-components` (if needed)
- `css-library` (if needed)
- `react-components` (if needed)
3. From the [repo's homepage](https://github.com/department-of-veterans-affairs/component-library) click on "Releases" in the right-hand sidebar.
4. Click on the "Draft a new release" button near the top of the page.
5. Click on the "Choose a tag" drop-down and type the letter `v` followed by the new "core" version number. The target should remain `main`.
- Example: `v16.1.0`
6. For the release title, type the same thing you entered for the tag.
- Example: `v16.1.0`
7. Click on the "Generate release notes" button.
- If the button is disabled, double-check that the tag/version number is correct and hasn't been released before.
8. Review the release notes for any typos and/or unneeded notes.
- The release notes are intended for public use so they should be professional in tone, easily understandable, and concise.
9. Ensure the "Set as the latest release" checkbox is checked.
10. Take a screenshot of the release notes and post in the `#platform-design-system-team` channel on Slack.
- This is to double-check that everything looks good, that there aren't any last-minute additions to the release that need to be included, and for general awareness of what will be released.
11. Click the "Publish release" button. GitHub Actions will take care of any necessary build and publishing steps.
- You can watch to make sure the release is created successfully from the [Github Actions tab](https://github.com/department-of-veterans-affairs/component-library/actions).
12. Create a PR for the following repositories that updates the `component-library` dependency versions:
- [vets-website](https://github.com/department-of-veterans-affairs/vets-website)
- [content-build](https://github.com/department-of-veterans-affairs/content-build)
- [vets-design-system-documentation](https://github.com/department-of-veterans-affairs/vets-design-system-documentation)

### How to choose a version number

This repo follows [semantic versioning](https://semver.org/). Here are some examples of which changes correspond to which version (MAJOR, MINOR, or PATCH) increase.
Expand All @@ -198,95 +293,4 @@ This repo follows [semantic versioning](https://semver.org/). Here are some exam

- Accessibility fix
- Styling fix
- Functionality fix

### Releasing
Copy link
Contributor Author

@jamigibbs jamigibbs Dec 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I moved the Releasing section up.


Releases will occur no less often than at the beginning of each sprint (every other Wednesday), and may additionally be performed as-needed when critical bug fixes need to go out. Please reach out to us via #vfs-platform-support or #platform-design-system if you have a need for an unscheduled release.

**For Design System Team only:**

1. If you are unsure if a new release should be created, check with the Release Manager and/or the rest of the team first, to make sure it's worth the effort at this time.
2. Get the version number from [`packages/core/package.json`](https://github.com/department-of-veterans-affairs/component-library/blob/main/packages/core/package.json#L4), ensuring it's up-to-date and new. If the core, web-components, and/or react-components packages versions haven't been updated yet, submit a PR to update them prior to performing the release, or things won't work correctly with the automation.
3. From the [repo's homepage](https://github.com/department-of-veterans-affairs/component-library) click on "Releases" in the right-hand sidebar.
4. Click on the "Draft a new release" button near the top of the page.
5. Click on the 'Choose a tag' drop-down and type the letter `v` followed by the new "core" version number (should look like `v16.1.0`). The target should remain `main`.
6. For the release title, type the same thing you entered for the tag (`v{versionNumber}`).
7. Click on the "Generate release notes" button. If the button is disabled, double-check that the tag/version number is correct and hasn't been released before.
8. Review the release notes for any typos and/or unneeded notes. Remember that these release notes are intended for public use, so they should be professional in their tone and appearance.
9. Take a screenshot of the release notes and post in the `#platform-design-system-team` channel on slack; ask for others to double-check that everything looks good and that there aren't any last-minute additions to the release that need to be included.
10. Back in GitHub, ensure the "Set as the latest release" checkbox is checked.
11. Press the "Publish release" button. GitHub Actions will take care of any necessary build and publishing steps.
12. If [vets-website](https://github.com/department-of-veterans-affairs/vets-website) will need to take advantage of the latest release sooner than later, open a PR to update the dependency version there (update your local copy and then submit a PR to merge the latest version bump).
13. Finally, go to your local copy of the [vets-design-system-documentation](https://github.com/department-of-veterans-affairs/vets-design-system-documentation) repo and update the version requirement, submitting a PR for that as well.

# Running Build via Storybook

1. `cd packages/web-components/`
1. `yarn install`
2. `yarn build`
3. `yarn build-bindings` (build React bindings)
4. `yarn watch:stencil` (optional)
2. `cd ../react-components/`
1. `yarn install`
2. `yarn build`
3. `cd ../core/`
1. `yarn install`
2. `yarn build`
4. `cd ../storybook/`
1. `yarn install`
2. `yarn storybook`

This will allow you to run Storybook locally to view all components

# Stencil Dev Server for Testing IE11
Copy link
Contributor Author

@jamigibbs jamigibbs Dec 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm removing the Stencil Dev Server for Testing IE11 section because it seems pretty outdated. We don't support IE11 anymore so there shouldn't be a need to test there right? I've only ever done development with Storybook. Is there any reason we should keep these steps?


1. Update `stencil.config.ts` line 16 to `buildEs5: true,`
1. [More information on buildEs5 in Stencil](https://stenciljs.com/docs/config#buildes5)
2. Stencil Dev Server is run in `dev` mode
2. Within `component-library/packages/web-components/src/index.html` Web Components can be added inside of the `<body>` tag for testing

1. Example:

```
<body>
<va-progress-bar label="Add a label here" percent={35}></va-progress-bar>
<va-segmented-progress-bar current={2} total={6}></va-segmented-progress-bar>
</body>
```

3. Run `yarn serve` inside `packages/web-components/` to start the Stencil Dev Server

## Testing

### Running tests for web components
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I moved the Testing section up.


To run unit tests for all components, the commands are:

```bash
yarn test
```

and

```bash
yarn test.watch
```

To test a single file, run:

```bash
npx stencil test --e2e -- src/components/[component-name]/test/[component-name].e2e.ts
```

Replace `[component-name]` with the name of the component you want to test. Optionally, you can add `--watchAll` after `--e2e` to watch the file for changes. For example:

```bash
npx stencil test --e2e --watchAll -- src/components/[component-name]/test/[component-name].e2e.ts
```

Another option is to use wildcards to query for certain tests. For example, to run all tests for the `va-accordion` component, you can run:

```bash
npx stencil test --e2e -- src/components/va-accordion/test/va-accordion-*
```
- Functionality fix
Loading